AI Assistant

12. AI Assistant

Lantide Data includes a built-in AI copilot (Agent) that understands your work state and operates the IDE directly (creating SQL tabs, running queries, editing Plan / Report). For the five-stage analysis flow, see §1.3; for a first full experience, see §2.

12.1 Open the AI Panel

Click the Astroid icon at the bottom of the icon rail on the right of the screen (the AI assistant) to expand the AI chat panel.

• Later launches: The panel defaults to collapsed; click Astroid to expand it. For the first-launch experience (auto-expand, Welcome Dialog), see §2.1.
• Background execution: Clicking Astroid again to collapse the panel, or switching to Export Tasks, does not stop an in-progress Agent reply; the chat area is only hidden, and streaming continues in the background (see §12.2).

12.2 Guards While the AI Is Generating

While the AI is generating a response, some actions may interrupt generation. To prevent you from accidentally interrupting the AI, the system adds a confirmation guard to the following actions—performing them pops up a confirmation dialog so you can decide whether to continue:

If you choose Cancel, the action does not run and the AI continues generating normally.

Actions that do not interrupt generation:

Tip: When the AI is not generating, protected actions run directly without showing a confirmation dialog.

12.3 Configure AI Connection Profiles

Before using the AI assistant, you need to set up a connection. On first launch, the system automatically creates a default OpenAI Profile (with the official Base URL and an empty API Key), and the WelcomePanel offers an "Open AI Settings" button to guide you through setup.

1. Click the settings icon (gear) in the AI panel, or the WelcomePanel's "Open AI Settings" button, to open the settings window.
2. Click "Add Profile" (or edit the default Profile) and choose a connection type:

• Ollama — Connect to a locally running Ollama model service.
• OpenAI — Connect to the OpenAI official API (the default Base URL is fixed to the official endpoint); enter an API key, after which you can fetch the model list via Refresh. If you use another compatible endpoint or a non-OpenAI provider, use Custom and fill in the Base URL yourself.
• Custom — A custom OpenAI-compatible API endpoint.

3. Fill in the corresponding settings (service URL, API key, etc.), then choose a model:

• OpenAI mode: The Base URL is the official default (read-only); after entering the API Key you can fetch the model list and choose a model (or type one manually). If a legacy configuration once pointed to a non-OpenAI endpoint such as Anthropic, switch to Custom.
• Ollama / Custom mode: There is a Refresh button beside the Model field; click it to automatically fetch the available model list from the server. If the fetch fails or the list is empty, it falls back to manual text input.

4. After saving, set that Profile as active.

You can create multiple Profiles and switch between them anytime from the dropdown at the top of the panel. Once setup is complete, the WelcomePanel automatically switches from the guided state to a short welcome message.

OpenAI / Custom Profiles can set Vision (pasted images) to "Auto-detect", "Supported", or "Not supported", used to decide whether screenshots can be sent to the model.

12.3.1 Paste Images in Chat (Vision)

Only OpenAI and Custom connections support pasting screenshots in the chat input box (Ollama does not).

1. Press Ctrl/Cmd+V in the input box to paste an image from the clipboard (e.g. a BI screenshot or an error screen).
2. The image appears in the pending-thumbnail row (48×48) above the input box; click the × at the top right of a thumbnail to remove an image before sending.
3. You can add text, then press Send; up to 4 images per message.
4. After sending, images appear above the text inside the user bubble (48×48), with the text below.

Limits and notes:

• Images are shown to the model for the current turn only; later conversation turns do not automatically carry historical images (re-paste them if you need to analyze again).
• If the model does not support Vision, the system prompts you; after you confirm, you can send text only (the images are not sent to the model, and no thumbnails are kept in the bubble).
• Bubble images in a sent message cannot be removed; regenerating a message that includes images resends the text only.

12.4 Agent Status Indicator

Below the AI panel's Top Bar is a fixed status bar that shows the AI Agent's current work state in real time. The state updates automatically with your actions (focus/unfocus a project, switch tabs, change Plan state, etc.), without manual triggering.

Click the ? button on the right of the status bar to open a help dialog with details about the Agent's capabilities in each state.

Tip: The status indicator's logic is fully synced with the backend—the state you see on the front end is the state the Agent is actually operating in. The tools the Agent can use differ by state (e.g. SQL Tab operations are only available in the Quick Analysis and Executing states). After entering the Executing state, the Agent reads the Plan first, then asks your preferred analysis execution mode (foreground / hybrid). Background agent analysis (chat-only) is offered only in Quick Analysis.

Tip: When the Agent is idle in the Executing state (e.g. it stopped responding due to an interrupt or timeout), the status description switches to a "Paused" hint. Return to the Plan tab and click the toolbar Continue button to resume execution (see section 11.6).

12.5 Two Analysis Modes: Quick vs Project

The AI assistant supports two analysis workflows and automatically chooses the appropriate mode based on your current state:

Quick analysis mode (no project required)

When you have no project focused (the status bar shows Quick Analysis), if you ask the AI for a data analysis, it first asks which approach you prefer:

• Quick analysis — Choose foreground SQL tabs, background agent analysis (chat-only), or hybrid; good for a one-off query or quickly validating an idea.
• Project analysis — The AI guides you to create a project and enter the structured "Plan → Execute → Report" workflow.

Tip: If you only ask a simple SQL question (e.g. "How do I PIVOT in DuckDB?"), the AI answers directly and does not ask you to choose a mode.

Project analysis mode (structured workflow)

When you have focused a project, the AI automatically enters project analysis mode. For the full flow (intake → Plan → annotate → Execute → Report), see §2.4–§2.7.

Two analysis execution modes (Plan Executing)

After the Plan enters the Executing state, the AI reads the Plan first, then asks, via an interactive question, your preferred analysis execution mode:

Background agent analysis (chat-only, no editor operations) is offered only in Quick Analysis; Plan Executing offers only foreground / hybrid. If a project Plan declares a background_materialized strategy during planning, choose Hybrid when Executing.

After entering Executing, the Agent's typical startup sequence is: read the Plan → ask the execution mode → write the Todo → run SQL per the mode (Pipeline stages must go through SQL tabs).

The AI asks the execution mode only once (within the same conversation) during the Executing stage. If you previously chose background mode in Quick Analysis, pressing Execute to start a new Plan still re-asks foreground / hybrid. If you have already expressed an Executing preference, the AI reuses it without asking again.

Pairing of Plan and Report

Each completed Plan produces a separate Report, paired one-to-one (Plan 1 → Report 1, and so on).

• After completing all analysis steps, the AI produces the full report in one pass and automatically marks the Plan as completed (Executed).
• The AI does not modify old Reports. Executing a new Plan only generates a new Report; fine-tuning an already-produced Report must be done through annotations or chat instructions.

Incremental editing of Plan and Report

When the AI needs to modify part of a Plan or Report (e.g. revising an analysis step based on your annotations), it prefers incremental editing (finding the section to modify and replacing only that section) over overwriting the whole document. This brings two benefits:

• More precise: Only the parts that need changing are modified, without affecting the rest.
• Live sync: If you are viewing the Plan or Report in the editor, the modified content is reflected in the editor immediately, without manually reopening it.

Tip: If you find that your needs are growing more complex during quick analysis (e.g. needing multi-step analysis or a formal report), the AI proactively suggests upgrading to project mode.

12.6 The AI Operates Your IDE Directly (UICommand)

This is the most powerful capability of the Lantide Data AI—the Agent is not just an "advisor with opinions" but a copilot that can operate your IDE directly.

Operations the AI can perform:

Query execution and step memory (Quick Analysis background / Executing hybrid modes):

• run_query / run_sql_tab: During Plan Executing, they must pass purpose (≤40 chars, the step's intent, written to the Query Step Ledger). run_query also infers whether to materialize based on context; for multi-step work you can use result_label for FROM references.
• Steps are also recorded in the conversation-level Query Step Ledger; you can optionally write [[QUERY_STEP]] in the body to add pitfalls.
• The system prompt injects a Recent Query Steps summary (without full SQL). The three-level path to trace back the full SQL: (1) query_result(result_id=...) (while the result is still in memory); (2) get_cache_source(cache_name=...|tab_id=...|result_id=...) (the result has spilled or expired but the cache still exists); (3) list_query_steps(include_sql=true) lists this conversation's steps. Humans can also right-click View SQL under Data → Cached (the same resolution source as get_cache_source).

All operations happen in front of you — when the AI creates a SQL Tab, you see the new tab appear; when the AI runs a query, you see results show in the results panel. You can take over or modify the AI's work at any time. For manual SQL or quick analysis examples, see §2.8, §12.5.

Tip (Agent query tools): During the exploration / trial phase, lightweight validation confirms the SQL is runnable (no data rows); a formal data pull previews up to 200 rows. Background queries materialize to the cache for multi-step analysis, multi-table JOINs, or complex CTEs, for later reference via FROM "step name"; foreground SQL tabs always materialize. You can right-click View SQL under Data → Cached to review the source. If an old conversation still shows the legacy tool name test_query, it is just a display of the old record.

Note: All of the AI's operations are read-only for data—it can create SQL Tabs and run SELECT queries, but cannot modify your original data files.

12.7 AI Interactive Questions (ask_user)

During analysis, the AI may need you to make a choice or confirm something. It then shows an interactive question block in the conversation:

• If the AI provides option buttons, just click the corresponding button to answer.
• If the AI needs a free-text reply, type your answer in the input box.

Common AI question scenarios:

• "Do you want a quick analysis, or to create a project for structured analysis?" (mode choice)
• "Please choose your preferred analysis execution mode: foreground auto analysis / hybrid" (Executing stage; Quick Analysis also offers background agent analysis)
• "Are you sure you want to mark the Plan as completed? This action cannot be undone."
• "There are several related tables—which would you like to analyze first?"
• "The exploration quota is exhausted—continue exploring?" (Options: Continue exploring / Stop for now)

Tip: The AI's questions appear as prominent interactive blocks in the conversation bubble, set apart from ordinary text replies. If you do not answer, the AI waits for your reply and does not proceed on its own. It times out automatically after more than 5 minutes without a reply.

12.8 Chat With the AI: Ask About Data, Generate SQL

Once setup is complete, you can type questions directly in the chat box, for example:

• "What columns does this dataset have?"
• "Why does this SQL error?"
• "Help me analyze the monthly total sales trend"

The AI assistant automatically references the data structure of your current workspace (table names, column names) to give answers that fit your actual data. Depending on the complexity of the question, the AI may:

• Answer directly: For simple questions, give an answer or SQL example directly.
• Create a SQL Tab and run it: For complex analysis needs, create a tab in your IDE, write, and run the query (see section 12.6).
• Ask your preference: Ask via an interactive question when confirmation is needed (see section 12.7).

Tip: While answering, the AI may validate SQL with validate_query or run a query for a preview with run_query; these operations are read-only and do not modify your data. Validation returns no data rows; a query preview is capped at 200 rows (see §12.6).

Tip (reviewing historical results): When you use query_result to read the result of an earlier run_query, the response can include an sql summary and cached_table_name (if materialized), making it easy to trace the query definition even after the conversation has been compressed.

Tip (with Markdown annotations): Plan / Report annotations are stored in the sidecar (*.annotations.json); the Agent obtains the mark-containing disk body and annotation_summary via read_plan / read_report (see §11.8).

12.9 AI Data Analysis Tools

Beyond SQL queries, the AI Agent also has a built-in set of statistical and machine-learning analysis tools that can complete advanced data analysis for you directly in the conversation—no extra packages to install.

How to use: You only need to describe your analysis need in natural language (e.g. "help me test whether these two groups differ significantly"), and the AI automatically chooses the appropriate tool. Before running any analysis tool, the AI always confirms with you first (via an ask_user interactive question), and only runs after you agree.

Available analysis capabilities:

How results are presented: The AI presents analysis results in a structured format in the conversation, including statistics, p-values, effect sizes, and a text interpretation, so you can understand the conclusion without consulting a statistics textbook.

Tip: In the quick analysis or project execution stage, the AI first prepares the data with SQL, then activates the needed statistical tools via activate_analysis and runs them. The plan-drafting stage only does data exploration and plan revision, not statistical analysis. In any stage, the AI confirms parameters with you before running an analysis.

Tip: The computed results of the analysis tools are presented in the conversation only; they do not modify your original data or cached tables.

12.10 AI Analysis Methodology

The AI Agent has a built-in structured analysis methodology that automatically identifies your analysis scenario and applies the corresponding best practices—you do not need to specify a methodology manually; the AI judges and applies it automatically.

Scenario identification: The AI classifies your analysis need into one of the following scenarios and decides its analysis strategy and validation focus accordingly:

Analysis quality assurance: Based on the identified scenario, the AI adds validation checkpoints to the Plan, reports effect sizes and significance in the statistical results, and attaches limitations to the Report. The funnel analysis requirements for stage definitions, denominator, and max drop-off have been demonstrated in §1.3, §2.5, §2.7.

12.11 Context the AI Senses Automatically (Context Engine)

Every time you send a message to the AI, the system automatically packages and sends the following information so the AI fully understands your work state—you do not need any extra action; it all happens automatically:

What does this mean?

• You do not need to tell the AI "what SQL I'm writing" — it already sees the content of your current tab.
• You do not need to repeatedly explain project background — once a project is focused, the AI automatically knows which analysis you are doing and how far along the Plan is.
• You can just say "help me use the clean_orders table" — the AI already knows which cached tables you have and what columns each has.
• You do not need to manually copy the error message — when a query fails, the AI automatically sees the full error content and the triggering SQL; just ask "why does this SQL error?" to get a fix suggestion.
• Markdown tab annotations go through the sidecar + MD marks — the Agent reads the mark-containing disk body and annotation_summary (see §11.8).
• Agent Memory — Only when the master switch is on and content has been written to the knowledge files does the model bring in your long-term memory; items pending approval in the queue are not injected (see Chapter 13).

Performance optimization: The system uses a tiered delivery strategy—each conversation turn automatically sends only a compact summary (workspace name, active tab title, cache table list, etc.), and when the AI needs to dig deeper it automatically calls internal tools to obtain the full context (column definitions, SQL content, project files, etc.), with no extra action from you. This greatly reduces the token cost of each conversation while ensuring the AI can still obtain full information when needed.

Advanced: The system prompt sent to the model is divided into core rules, current work-state guidance, and a context summary; the full list of callable tools comes from the function definitions the model receives, not from being re-listed in the state guidance.

Privacy note: Context data is assembled and sent to the AI model service you configured (Ollama / OpenAI / Custom) only at the moment you send a message, and is not stored on any third-party server.

12.12 Context Usage Ring

On the right of the AI input box (beside the Send button) is a small Context Usage ring that lets you monitor the current conversation's token consumption in real time:

• The ring shows the context usage ratio as an arc-shaped progress bar—the longer the arc, the more is consumed.
• Hover over the ring, and the tooltip shows detailed values, e.g. 42.3% · 18.5K / 43.7K context used.
• It only appears after the AI has replied at least once (once there is token usage data).
• Switching to a new conversation resets the ring.

Tip: If you specify a custom context window size (≥1024 tokens) in the AI Profile settings, the ring's denominator uses your custom value rather than the model-reported default.

Tip: After you switch or edit the model / context window settings of an AI Profile, the ring automatically clears the old value and re-fetches the latest usage, ensuring the displayed figures match the current model.

12.13 Conversation Token Usage and Truncation Warnings

The system automatically manages the output token limit of each AI reply to avoid truncating responses as much as possible. In extreme cases, a warning marked with a prominent amber border appears in the conversation:

Tip: In most cases you will not see these warnings. The system automatically attempts to continue in the background, and only shows a warning when auto-continue still cannot complete.

12.14 Live Presentation of the AI's Thinking and Tool Calls

While replying, the AI assistant may go through multiple steps—thinking, calling a tool, obtaining a result, and continuing to reply. These steps are stacked segment by segment in the conversation in the actual chronological order they happen, so you always know what the AI is doing.

Five block types:

Fenced code blocks in chat:

For a multi-line ``` code block, after streaming completes you can move the pointer into the block, and a toolbar appears at the top right (left to right: Open in new SQL tab → Copy):

• While streaming: The toolbar is not shown while the last body segment is still being output; it appears only after completion.
• Touch devices (v1 limitation): Without hover capability, the toolbar may not be visible; wait for streaming to complete and use a desktop mouse instead, or manually create a SQL tab and paste the content.

Behavior while streaming:

• The Thinking and Tool Call blocks have a maximum height limit; when exceeded, they auto-scroll downward with a gradient fade-out at the bottom, ensuring they never take over the whole screen.
• After streaming completes, the Thinking and Tool Call blocks collapse automatically, leaving only a one-line summary (such as "Thinking (12 lines)" or "tool_call: show_tables" / the SQL summary of validate_query), so you can focus on the final reply. Click to expand when needed.

Conversation scrolling:

• When a new message arrives, the conversation area auto-follows and scrolls to the bottom.
• If you scroll up to read (including scrolling inside a Thinking / Tool block), auto-follow pauses, and a circular down-arrow button appears at the bottom right.
• As long as auto-follow is paused, the button is always shown (even if you have manually scrolled to the very bottom).
• Once paused, you must click the button or send a new message to resume following; the end of Agent generation does not automatically jump back to the latest message.
• Clicking the button resumes following and scrolls to the latest message, after which the button hides.

Automatic grouping and collapsing of Tool Calls:

When the AI issues 3 or more tool calls in a row, the system automatically collapses these calls into a single "N tool calls" group, preventing a large number of expanded tool blocks from filling the conversation view. Click the group title to expand and see the details of each tool call.

Activity indicator:

During an AI reply, there are phases where the AI is working but has not yet produced visible text (e.g. while a tool call is executing, or when re-calling the LLM between iterations). To eliminate the feeling that "the screen has frozen", the system automatically shows a trailing spinner and status text hint during these silent periods (e.g. "Processing tool calls...", "Thinking..."), telling you the Agent is still working normally. The spinner also persists during tool calls and is only cleared once the tool returns its result, avoiding flicker. In addition, when the AI's reply text streaming pauses for more than a few seconds (e.g. while the model internally organizes tool calls), the system also automatically shows a "Working..." spinner, so you know the AI is still working normally.

Tip: The stop button uses a neutral gray design to reduce visual intrusion, so you notice it only when you need it.

File changes bar (File changes):

When an AI reply successfully writes to a workspace file within that turn, a file changes bar appears at the bottom of the message (between the body and the Copy / Fork action row), summarizing the resources this reply affected—so you can track which files the Agent touched without expanding multiple Tool Calls.

Undo limits and semantics:

• Safe mode: If, after the Agent's write, you manually edited that file's body, the system detects that the content has diverged from the Agent's write result and blocks the undo, warning of a conflict—handle it instead via annotations, chat, or a manual restore.
• Newly created files: For a Plan / Report / SQL tab / HTML that the Agent created within this reply, undo clears the content but keeps the file and tab row (it does not delete the file or close the tab).
• add_report side effect: If this reply's add_report already moved the Plan into Executed, undoing that Report row may be blocked due to the Plan state side effect; handle the Plan state manually as prompted.
• Scope: Undo only targets writes within a single assistant reply—it does not cross messages or conversations, and has nothing to do with git.
• Reloading the conversation: Undone rows are marked as restored; after reopening a historical conversation, you can still see the change bar and stats.

Tip: Annotation Resolve, the Query Step Ledger, run_query materialized cache, Reference file writes, and the like are not in scope for the file changes bar. The Plan progress sidecar (Todo) is presented by the Progress panel, see §11.6.

Message actions (Message Actions):

On the outer right edge of each AI reply's message bubble, action buttons are shown:

The Fork icon is shown only after the reply has been fully persisted. If a reply was stopped midway, or a tool round has not finished writing, it cannot be forked.

Tip: If the source conversation has an in-progress ask_user interaction, you can still Fork on other completed replies; the source conversation's question is unaffected.

Tip: If the model you use (e.g. DeepSeek-R1, QwQ) embeds <think> tags in its reply, the system automatically intercepts these tags and correctly classifies their content as a Thinking block, so it does not appear in the body text.

12.15 Conversation Management (New / Switch / Delete / Clear All)

• New conversation: Click the "New" button at the top of the AI panel to open a brand-new conversation (blank context).
• Fork a conversation (Fork): Click the Fork icon in the action row of a completed AI reply to copy the full conversation record up to that reply (including the tool trace) into a new conversation and switch to it automatically. The difference from "New conversation" is that Fork preserves the existing context, which is suitable for exploring different hypotheses in parallel without losing the original analysis thread.
• Automatic naming: After the first message of a new conversation is sent, the system automatically generates a concise conversation title using the LLM, shown in the conversation history list in real time. If automatic naming fails, the system uses the first few characters of the message as a fallback title. Titles produced by Fork are prefixed with Fork ·.
• Manual rename: Move the cursor over the conversation title area in the Top Bar to reveal a pencil icon. Click it to enter inline edit mode (the text is automatically selected), then press Enter to confirm or Escape to cancel. The title can be up to 60 characters. Changes sync to the conversation history list in real time.
• Switch conversation: Click the history icon in the Top Bar to pop up an overlay menu where you can search, browse, and switch to a previous conversation. Conversations are grouped by date (Today / Yesterday / Earlier), with the currently active conversation highlighted.
• Delete conversation: Click the delete button in the conversation history overlay to remove a conversation you no longer need.
• Clear all history: Below the search box in the conversation history overlay, click the Clear All History button to clear all historical conversations at once. The system shows a second confirmation prompt, and after you confirm it deletes all conversations but keeps the conversation currently in progress.

Each workspace's conversation records are independent.

12.16 Connection Status Indicator

At the top of the AI panel is a connection status light:

• Green — Connection is normal; you can start chatting.
• Red / gray — Connection issue. Click for error details, and check that the Profile settings are correct.

[Image] AI chat panel: the conversation UI, Agent status indicator, and connection status

[Image] AI settings window: the Profile configuration screen

Design note: For analysis modes and ask_user, see Data analysis workflow in the Agent era §§2 and 10; for statistical tools and methodology guardrails, see Data analysis workflow in the Agent era §11; for context engineering, see Prompt and context engineering.