Makinist

Makinist is the AI assistant that runs on the SQL Query Writing screen of the Compass module. It takes the tables in the selected data source as context, forwards natural-language requests to a Langflow flow, and returns them as executable SQL. The generated SQL block can be transferred to the editor with a single click.

Supported Data Source Types

The Makinist chat is available for data sources in Compass's SQL group (PostgreSQL, MSSQL, MySQL). This feature is not present on MQTT, REST API, or Excel query screens because the queries there are not in SQL format.

Prerequisite

Makinist works only with SQL-type data sources (PostgreSQL, MSSQL, MySQL). These data sources must first be defined in the Port module.

You can use ${variable} syntax in SQL queries with Global Variables. For dynamic user parameters → Compass Parameters

1. Opening the Chat

While writing a new SQL query in Compass, click the Write with AI button in the top action area of the page.

UI Element	Behavior
Write with AI button	Opens the chat panel; title changes to `Makinist`, icon `palette` → `smart_toy`
Close Chat button	Takes the same button's `Close Chat` label when open; hides the chat
New Session	Creates a new `username_DatasourceName_Mon_HH:mm:ss` ID and makes it the active session

When the chat opens, the screen is split into two sections: the message history and input area on the left, and the session selector dropdown at the top.

2. Table Selection (Providing Context)

For Makinist to generate correct SQL, it needs to know the tables it will query. Therefore, at least one table must be selected before sending each message.

Table Selector Behavior

Click the table_chart icon button to the left of the input line.
In the modal sheet that opens, all tables in the data source are listed (taken from Compass's tablesResponse list).
Select one or more tables and close with OK.
Selected tables appear as chips above the input; each chip can be removed individually with its x icon.

State	Result
No table selected	Message cannot be sent; "Please select at least one table and write a message." warning appears
Table selected but message is empty	Same warning appears
Table selected and message written	Request is sent to Langflow with the `ask_agent` action

Fewer Tables, Clearer Query

Selecting 10+ tables at once makes it harder for the model to identify the right table. Selecting the minimum set of tables needed for the query generally produces more accurate SQL.

3. What Happens When a Message Is Sent?

When you press Send, Makinist sends the following package to the Langflow API:

Package Component	Source
`prompt`	The text you typed in the input field
`id`	`compassController.selectedDataSourceId.value` (selected data source ID)
`table_name`	List of selected table names
`ds_type`	`compassController.selectedDataSourceType.value` (postgresql / mssql / mysql)
`session_id`	Active session ID

flowchart LR
    A[Table selection] --> P[Prompt]
    P --> Q[ask_agent action]
    Q --> L[Langflow API]
    L --> R[SQL code block returned]
    R --> M[Markdown render]
    M --> U[Use SQL button]

A temporary typing... bubble appears in the message list while waiting for the response. It is removed when the response arrives and the real message is added.

Cancelling a Request

While waiting for a response, the Send button turns into a stop icon. When clicked:

The HTTP client is closed via _httpClient?.close().
The typing... bubble is removed.
Sending a new message becomes available again.

4. Code Blocks in Responses

Makinist messages are rendered as Markdown. Code blocks (wrapped with ```) appear with an extra header bar:

Button	Behavior
Copy	Copies the entire code block to the clipboard; shows a "Copied to clipboard" SnackBar
Use SQL	(Visible only on `sql`-language code blocks) — transfers the content to `compassController.codeSQLController.text`, parses parameters, and automatically closes the chat

flowchart LR
    A[AI response] --> B{Code block present?}
    B -->|Yes, sql| C[Use SQL + Copy]
    B -->|Yes, other language| D[Copy only]
    B -->|No| E[Plain Markdown]

Before Using the Query

The Use SQL button pastes the generated query into the editor as-is; Compass does not run it automatically. It is recommended to review it manually first, then test it with Run.

5. Session Management

Makinist maintains data-source + timestamp-stamped sessions per user.

Session Naming Format

{username}_{DatasourceName}_{Mon}_{HH:mm:ss}

Example: furkan_PrdLineDB_Oct_14:32:08

Component	Source
`username`	`GetStorage().read('username')`
`DatasourceName`	Name of the selected data source (spaces removed)
`Mon`	English 3-letter month (`Jan`, `Oct`, etc.)
`HH:mm:ss`	Local time

Switching Sessions

You can switch to past sessions using the dropdown on the top panel of the chat. When a new session is opened it is added to the top of the list; if you switch to another session without sending a message, the empty session is automatically cleaned up.

Deleting a Session

The delete button appears when the active session has at least one message. When deleted:

The delete_session action runs in Langflow.
A new empty session is created and made active.
The message history is cleared.
The deleted session is removed from the list.

6. Tips for Writing Good Prompts

Question Type	Example
Filter + aggregation	"Give me total production count per line for the last 7 days"
JOIN	"Join the orders table with the customer table and summarize revenue by customer for the last 30 days"
Date-based	"Calculate the hourly average downtime for this month"
Top-N	"List the 5 machines producing the most errors"
Pivot-like	"Spread production count by shift into columns"

Providing Schema Knowledge

Makinist can know table column names through metadata provided to the Langflow flow; however, business rules (e.g. "downtime = status_code = 'D'") are not sent to the model, so answers can be wrong. Write such rules explicitly in the prompt:

"Treat downtime as status_code = 'D'. List total downtime duration per machine for the last 24 hours."

7. Persistence of History

The chat history is stored on the Langflow side via session ID. When the browser is closed and reopened:

getSessions fetches the session list for the user again.
When a session is selected, getSession loads the message history.
Messages are printed to chat separated into User and Makinist roles.

User messages are stored in the DB as JSON ({"prompt": "..."}); the UI decodes and displays them.

Data Source Mismatch

If the active data source does not match the source the session was created with, the input field is disabled ("Input disabled because the chat history is not compatible with the selected data source."). You need to start a new session.

8. Limitations

Visible only for SQL-group data sources (PostgreSQL, MSSQL, MySQL).
Response quality depends on the Langflow flow configuration and metadata richness.
For very large tables, the model may misinterpret the schema in complex JOINs.
When the service is unreachable, the request returns an error; the chat remains empty.
Only one request is supported at a time; you must cancel before sending a new message while waiting for a response.

9. Troubleshooting

Symptom	Possible Cause	Solution
Button is unresponsive	`pirivision-langflow-api` service is not running	Contact your system administrator
"Please select at least one table..."	No table selected or prompt is empty	Select a table from the table icon, write a message
Response stays at `typing...`	Request may be hanging	Cancel with the Stop button, try again
Generated SQL returns an error	Schema was misinterpreted	Narrow table selection or clarify the prompt
History not loading	`get_session_history` action returned 4xx/5xx	Contact your system administrator

10. Next Step

→ CaptainAI — Horizon Board Assistant → AI Ecosystem — Overview → Ecosystem