docs/capabilities.md

Capabilities (Current “What the App Does”)

This document describes what ConverTA does today, independent of any past roadmap.

Modes

• AI-to-AI

  • Runs a simulated healthcare survey interview between:
    • an automated Surveyor agent and
    • a synthetic Patient agent.
  • When the run completes normally, the app performs post-run analysis and seals the run.

• Human-to-AI

  • Lets a human play one side of the conversation while the other side is generated by the LLM.
  • Ending the session triggers the same post-run analysis and seals the run.

• Upload Text

  • Paste a transcript or upload a text/PDF file (best-effort PDF extraction).
  • Runs the same analysis pipeline and seals the run.

• History

  • Lists sealed runs (shared/global) and allows read-only replay:
    • transcript
    • analysis output
  • Exports from History use server-canonical run data.

• Configuration

  • Review/edit system prompts and agent configuration.
  • Create/duplicate/edit/delete user personas.
  • Create/duplicate/edit/delete analysis frameworks (bottom-up + rubric + top-down); default framework is read-only and can be duplicated.

Persistence (Server-Canonical)

ConverTA uses SQLite for persistence.

• DB_PATH controls the SQLite path.
  • Local Docker default: .localdata/...
  • Hugging Face Spaces default: under /data/...

Persisted artifacts:

• Sealed runs (transcript + analysis + evidence catalog + config snapshots)
• Personas (defaults + user-created) with versioning
• Shared settings (system prompts + active analysis framework id)
• Analysis frameworks (bottom-up + rubric + top-down) with versioning

Notes:

• Sealed runs are immutable.
• “Stop/abort” during a live run does not produce a sealed run.
• If the resource agent fails (e.g., OpenRouter errors), the UI surfaces retry attempts and a failure notice.

Personas

There are two persona kinds:

• Surveyor personas

  • Editable fields (user personas):
    • attribute list (bullet-style strings)
    • question bank (list of target questions)
  • Selection of which Surveyor is used for a run happens in the run panels (not in Configuration).

• Patient personas

  • Editable fields (user personas):
    • attribute list (bullet-style strings)
  • Selection of which Patient is used for a run happens in the run panels (not in Configuration).

Default personas:

• A small seeded set exists for each kind.
• Defaults are view-only in the UI (to prevent breaking the app by deleting/over-editing baseline personas).

System Prompts (Universal per agent type)

These are shared, DB-backed “universal” system prompts:

• Surveyor system prompt (applies to all surveyor personas)
• Patient system prompt (applies to all patient personas)
• Analysis agent system prompt (applies to all analyses)

The Configuration UI provides:

• “Apply defaults”
• A warning/acknowledgement gate before editing the system prompt text.
• Default analysis frameworks are read-only and must be duplicated to edit.

Analysis

Analysis runs post-conversation (or on uploaded text) and produces evidence-backed outputs:

• Bottom-up findings (emergent themes)
• Care experience rubric (fixed buckets: positive / mixed / negative / neutral)
  • Includes a model-rated split across positive/mixed/negative (for a pie chart summary)
• Top-down codebook categories (template-driven)

Analysis execution (3-pass)

For reliability and smaller-model compatibility, the analysis pipeline runs as three sequential LLM calls:

1. Bottom-up findings
2. Care experience rubric
3. Top-down codebook categories

In the UI, each column populates as its pass completes, while later passes show as pending/running.

Analysis frameworks

• An analysis framework defines:
  • bottom-up instructions + attributes
  • rubric instructions + attributes
  • top-down instructions + attributes + codebook categories (optional per-category descriptions)
• Frameworks are managed in Configuration (create/duplicate/delete + edit the framework).
• The active framework is selected per run using the dropdown next to the 📊 Analysis header in:
  • AI-to-AI
  • Human-to-AI
  • Upload Text
• Runs snapshot the selected framework so History replay and exports remain stable.

Exports

• Excel (.xlsx) multi-sheet export and lossless JSON export are available after analysis completes.
• When a run is sealed, exports are generated from server-canonical persisted data.
  • There is a client-side fallback export for non-sealed sessions.

Access Control (Prototype)

If APP_PASSWORD is set:

• UI is gated behind a login overlay.
• API access requires the session cookie, or the internal header used by the UI WebSocket bridge.