AI Ecosystem

The Pirivision platform provides two separate AI assistants to help users query data faster and reach insights on their dashboards. Both assistants connect to Langflow flows through the pirivision-langflow-api service (port 7870), but their contexts and purposes differ.

flowchart LR
    A[Compass<br/>Query Editor] -->|Table + Prompt| M[Makinist]
    B[Horizon<br/>Board] -->|Snapshot + XLSX + Prompt| K[CaptainAI]
    M --> L[Langflow API]
    K --> L
    L --> M
    L --> K

Backend Dependency

Both assistants require the pirivision-langflow-api service to be running. When the service is unreachable, Makinist's chat window cannot produce a response, and CaptainAI messages stay in typing... state.

Makinist — Compass SQL Assistant

Makinist is the AI chat panel that opens beside the SQL query editor in Compass. When the user selects tables from the data source and asks a question in natural language, Makinist generates executable SQL and transfers it to the editor with a single click.

Feature	Description
Module	Compass — SQL Query Writing screen
Context	Selected data source + selected tables + chat history
Output	SQL code block (Markdown format)
Key Button	`Use SQL` — transfers the generated query to the editor
Session Mgmt	Separate session history per data source, per user
Backend	`pirivision-langflow-api` (action: `ask_agent`)

→ Makinist — Detailed Guide

CaptainAI — Horizon Board Assistant

CaptainAI (in the Turkish interface: Kaptan AI) is the chat dialog that opens when the floating button in the bottom-right corner of a Horizon board is clicked. Operators can have the board's live view and widget data interpreted in natural language — for example, asking "what caused the downtime in shift 2?"

Feature	Description
Module	Horizon — Board screen
Context	Board PNG snapshot + all widget XLSX data + question text
Output	Natural language response (Markdown + LaTeX supported)
Key Feature	Can interpret board visuals ("the top gauge", "this chart")
Session Mgmt	Per-board `KaptanSessionItem`
Backend	`pirivision-langflow-api`

→ CaptainAI — Detailed Guide

When to Use Which Assistant?

Scenario	Recommended Assistant
I need to write SQL against a database I'm unfamiliar with	Makinist
I want to interpret an anomaly on a board	CaptainAI
I want a quick shift summary / commentary	CaptainAI
I need an analysis that requires JOIN across tables	Makinist
Which widget peaked which parameter?	CaptainAI
I want to save the query and turn it into a chart in Cartography	Makinist

Two-Phase Flow

In most cases the two assistants complement each other:

Write the query in Compass with Makinist → convert to a widget in Cartography
Chat over those widgets on the Horizon board with CaptainAI

Shared Behaviors

Both assistants run through the Langflow API and share some common behaviors:

Behavior	Description
`typing...` Placeholder	A temporary "typing..." line is added to the message list when a request is sent; removed when the response arrives.
Cancel	While waiting for a response, the same button turns into a stop icon; clicking it cancels the HTTP request and removes `typing...`.
Error Handling	If the service returns an error, a SnackBar notification is shown. The error is not saved to the persistent chat.
Markdown	Responses are rendered as Markdown (code blocks, headings, lists).

Sensitive Data

Both assistants send the user's query and context (tables / board snapshot / XLSX) to the Langflow service. Be mindful of what context is exported when working with tables or boards that contain sensitive data.

Next Step

→ Makinist — Compass SQL Assistant → CaptainAI — Horizon Board Assistant → Port — Data Sources → Automation — Rule-Based Alerts