AI Assistant¶
Overview¶
The AI Assistant tab combines offline, rule-based tools (no API key) with an optional cloud LLM for interpretation and writing help. Main capabilities:
- Workflow checklist: Live preflight status (peaks loaded, database, results, fragment data, LLM configured).
- Offline actions: Screening diagnosis, copy Methods, Results draft, fragment JSON snapshot.
- LLM tasks: Workflow guide, Top 5/10/20 hit interpretation, diagnosis restatement, Methods polish, fragment compare/consensus/narrative.
- Free-form chat: Ask questions in the conversation panel (uses wizard-style prompt with current context).
- Logging: Successful LLM calls append a line to
GUI_result_files/ai_log.jsonl.
LLM features require Edit → Preferences or environment variables (see step ②).
Interface Layout¶
Left panel (~300 px)
- Workflow & offline tools scroll area (preflight text).
- Refresh status
- Actions grid: Screening, Copy Methods, Results draft, Fragment JSON
Right panel
- LLM assistant status line (connected / missing API key).
- Provider dropdown (DeepSeek, OpenAI, DashScope, Custom).
- API settings button → same dialog as Edit → Preferences.
- LLM actions and Fragment button groups.
- Include fragment context checkbox; Sample note field.
- Conversation (read-only log) + input row: Send, Stop, Clear.
Entry points from other tabs:
- Molecular Analysis: AI: Top 5 →, results table context menu, Compound Details → AI: Interpret candidate
- Fragment Analysis: AI: Fragment attribution narrative, fragment table context menu
Workflow¶
① Check workflow status (no API)¶
- Open the tab; read the workflow banner (peaks, database, analysis results, fragment steps).
- Click Refresh status after completing steps on other tabs.
- Click Screening for a rule-based diagnosis (filters, peaks, hit count) appended to the conversation.
② Configure LLM (optional)¶
Edit → Preferences or API settings on this tab.
| Field | Description |
|---|---|
| Provider | Preset base URL and model (recommended: DeepSeek v4 Flash) |
| API Key | Paste from provider console, or use env VIRMOL_LLM_API_KEY |
| Model | Filled from provider; editable in Custom mode |
| API base URL | Read-only for presets; editable for Custom |
| Temperature | 0.0–1.5 (default ~0.2) |
Environment variables (override or supplement saved settings):
VIRMOL_LLM_API_KEYVIRMOL_LLM_BASE_URLVIRMOL_LLM_MODELVIRMOL_LLM_PROVIDERVIRMOL_LLM_TEMPERATURE
Status line turns green when a key is present: Connected: {provider} · {model}.
③ Run offline document tools¶
| Button | Output |
|---|---|
| Copy Methods | English Methods paragraph → clipboard (from current GUI parameters) |
| Results draft | Rule-based Results section → clipboard; uses Sample note if set |
| Fragment JSON | Structured fragment snapshot → clipboard (requires fragment data) |
④ Interpret screening hits (LLM)¶
Prerequisite: Start Analysis with ≥1 row in the results table.
| Button | Description |
|---|---|
| Workflow guide | Suggested next steps in the pipeline |
| Top 5 / 10 / 20 | Narrative for top N hits (larger N uses higher token budget) |
| Restate diagnosis | LLM version of rule screening diagnosis |
| Polish Methods | Refine Methods draft in English |
- Enable Include fragment context to attach Phase-A fragment data to Top-N tasks (richer, larger prompts).
- Wait for completion; use Stop only if needed (may yield empty reply).
⑤ Fragment LLM tasks¶
Prerequisite: Fragment Analysis → Run masking attribution (extraction recommended).
| Button | Description |
|---|---|
| Compare masking | Compare attribution across candidates |
| Global consensus | Recurring fragments in global table |
| Candidate attr. | Narrative for candidate selected in Fragment Analysis combo |
Fragment table right-click: explain one fragment row or full candidate attribution.
⑥ Free-form question¶
- Type in Ask a question… → Send or Enter.
- Context includes workflow state and top candidates (similar to workflow guide).
⑦ Output¶
GUI_result_files/
ai_log.jsonl # timestamp, task, model, context hash, reply length
Conversation text is shown only in the GUI unless you copy it manually.
FAQ¶
- "LLM API not configured"
Set API key in Preferences or VIRMOL_LLM_API_KEY.
- Empty Assistant reply
Request may have been stopped, timed out, or prompt too large — try Top 5 instead of Top 20; verify model and key.
- "Wait for the current AI request"
Only one LLMThread at a time; wait or Stop.
- Fragment buttons warn no masking data
Run Run masking attribution on Fragment Analysis first.
- Top 5 from Molecular Analysis does nothing
Results table must have ≥1 row after Start Analysis.
- Disclaimer at end of LLM text
Intentional for non–Methods-polish tasks; verify all scientific claims manually.
Relation to Other Modules¶
- Molecular Analysis: Source of peaks, filters, evaluator choice, Result.csv, and Copy methods text; AI: Top 5 → jumps here.
- Fragment Analysis: Masking and fragment tables feed Fragment LLM tasks and optional Top-N context.
- Database Management: No direct dependency; custom libraries affect screening context indirectly.
- Other Tool: No link.