​

Report Chat — Interactive Q&A on Your Last Run

• Defaults to your latest run via the database (no paths required)
• If you decline using the latest, it presents a styled, readable table of recent runs and lets you pick one by number
• Robust to auto-backups and renames; paths are resolved automatically
• Clear, friendly messages and clean cancel behavior

Note: Report Chat uses an LLM to answer questions about your run context. You need a valid OPENAI_API_KEY (or compatible) to chat. The “create” reporting command can still generate deterministic methods text without an API key.

​

Quick Start

autocleaneeg-pipeline report chat

1. The CLI finds your latest run in the database
2. It resolves any backup move recorded for that run
3. It tries to load llm_reports/context.json; if not found, it reconstructs a minimal context from:
   • *_processing_log.csv (per-file log) and
   • *_autoclean_report.pdf (standard report)
4. It starts an interactive prompt for your Q&A

​

Prerequisites

• A completed (or failed) run stored in the database
• Standard outputs on disk for that run:
• Per-file processing log CSV (saved under reports/run_reports/ with a copy in exports/)
• PDF report under reports/run_reports/
• For LLM chat: OPENAI_API_KEY (and optionally OPENAI_BASE_URL for compatible providers)

You do NOT need to have enabled ai_reporting; chat reconstructs context from always-present outputs when a saved LLM context is missing.

​

Default Behavior (Latest Run)

1. The CLI initializes the database path to your workspace output directory.
2. It queries the latest run (by created_at / id) from the pipeline_runs table.
3. If a directory backup was recorded for that run, it applies the backup-aware resolver to locate moved folders.
4. It prompts: “Use latest run?” with a summary of run id, time, and task.
   • Yes/Enter → chat starts on that run.
   • No → you’re shown a rich, interactive table of recent runs.

​

Interactive Run Selector

• Columns:
  • #: index to select
  • Run ID: short form of the unique id
  • Created: timestamp
  • Task: task/class name
  • File: original input file name
  • Status: e.g., completed, failed
  • Success: Yes or No
  • Backup: Yes if a directory backup was recorded for this run
  • Artifacts: count of output artifacts (from json_summary when present)

​

How Context Is Built

1. Preferred: Use llm_reports/context.json if it exists (created by report create or during automatic LLM reporting if enabled)
2. Fallback reconstruction: A minimal, but sufficient context is built from:
   • Per-file *_processing_log.csv (always written after runs)
   • *_autoclean_report.pdf path for reference
   • The run record (for run_id, task, input_file)

• filter_params: high/low-pass, notch freqs/widths
• epochs: epoch limits and totals (kept + rejected when available)
• ica (best-effort): total components and removed indices
• resample_hz, durations_s, n_channels
• figures.autoclean_report_pdf: the PDF path if present
• notes: includes flags when present in the CSV

The reconstruction is designed to be robust, using only always-present outputs. If llm_reports/context.json exists, it is used as-is.

​

Backup-Aware Path Resolution

{
  "directory_backup": {
    "moved_from": "/.../RestingStateTutorial",
    "moved_to": "/.../RestingStateTutorial_backup_YYYYMMDD_HHMMSS",
    "effective_at": "ISO timestamp",
    "initiated_by_run_id": "<this run>",
    "scope": { "task_root": "/.../RestingStateTutorial" },
    "reason": "existing directory found; moved to backup"
  }
}

​

Manual Context Mode (Optional)

autocleaneeg-pipeline report chat --context-json /path/to/context.json

​

Environment & Security

• OPENAI_API_KEY — required to chat (OpenAI-compatible provider)
• OPENAI_BASE_URL — optional; set for compatible self-hosted endpoints

• Report Chat does not persist your chat content. It submits a short prompt to the LLM with the context, and displays the LLM’s JSON answer.
• The separate “report create” command writes an llm_trace.jsonl (with hashed user content) for transparency. Chat does not append to this trace.

• Chat is not gated by the compliance authentication decorator. If your deployment requires extra gating, please coordinate with admins.

​

Examples

# Uses latest run via DB, resolves backups, and starts Q&A
autocleaneeg-pipeline report chat

Use latest run?
Run 01K4K993… on 2025-09-07 19:48:14 (task: RestingStateTutorial)? [y/n] (y): y
> How many components were removed?

autocleaneeg-pipeline report chat

#  Run ID   Created                 Task                  File             Status     Success  Backup  Artifacts
1  01K4K…  2025-09-07 19:48:14     RestingStateTutorial  128_…raw         completed  Yes      Yes     7
2  01K4K…  2025-09-07 17:31:03     RestingStateTutorial  128_…raw         completed  Yes      No      7
…
Select a run number (Enter to cancel): 1

autocleaneeg-pipeline report chat \
  --context-json /path/to/context.json

​

Troubleshooting

• “Could not locate latest run context or reconstruct from outputs.”
  • Ensure there is at least one run in the DB (process a file via the pipeline)
  • Ensure your per-file processing log CSV and PDF are present for that run
  • If using manual JSON mode, verify the path and format
• Missing API key
  • Set OPENAI_API_KEY in your shell: export OPENAI_API_KEY=sk-...
• Interactive table “style” errors
  • Chat now uses AutoClean’s themed console; styles like title/header are defined. If you see style errors, update the CLI to the latest build.
• Graceful cancel
  • Press Enter at the selection prompt to cancel without error (exit code 0).

​

FAQ

​

See Also

• autocleaneeg-pipeline report create — Generate methods + executive summary + QC narrative (writes trace, requires API key for LLM parts)
• docs/directory-backup-resolution.md — How path resolution works with auto-backups (Phase 1/2 plan)