helia/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Context: Bachelor Thesis

Title: A Modular Agent Framework for Therapeutic Interview Analysis Goal: systematically compare local-first/on-premise LLMs against cloud-based state-of-the-art models for a specific therapeutic task (PHQ-8 assessment).

Core Hypothesis: Small quantized language models running locally can provide analytical performance comparable to large cloud models when supported by an appropriate agentic framework.

Key Requirements:

• Privacy-First: Architecture must support local/on-premise execution to address clinical data privacy concerns.
• Modularity: The system must allow easy swapping of underlying models (Tier 1: Local, Tier 2: Self-hosted, Tier 3: Cloud).
• Benchmark: The system is evaluated on its ability to accurately map therapy transcripts to PHQ-8 (Patient Health Questionnaire) scores using the DAIC-WOZ dataset.

Commands

• Install Dependencies: uv sync
• Run Agent: python -m helia.main "Your query here"
• Verify Prompts: python scripts/verify_prompt_db.py
• Lint: uv run ruff check .
• Format: uv run ruff format .
• Type Check: uv run ty check
• Test: No test suite currently exists. (Priority Roadmap item)

Architecture

Helia is a modular ReAct-style agent framework designed for clinical interview analysis.

Core Modules

1. Ingestion (src/helia/ingestion/):

   • Parser: TranscriptParser parses clinical interview transcripts (e.g., DAIC-WOZ dataset).
   • Loader: ClinicalDataLoader in loader.py retrieves Transcript documents from MongoDB.
   • Legacy: S3DatasetLoader (deprecated for runtime use, used for initial population).

2. Data Models (src/helia/models/):

   • Transcript: Document model for interview transcripts.
   • Utterance/Turn: Standardized conversation units.
   • Prompt: Manages prompt templates and versioning.

3. Assessment (src/helia/assessment/):

   • Evaluator: PHQ8Evaluator (in core.py) orchestrates the LLM interaction.
   • Logic: Implements clinical logic for standard instruments (e.g., PHQ-8).
   • Schema: src/helia/assessment/schema.py defines AssessmentResult and Evidence.

4. Persistence Layer (src/helia/db.py):

   • Document-Based Storage: Uses MongoDB with Beanie (ODM).
   • Data Capture: Stores full context (Configuration, Evidence, Outcomes) to support comparative analysis.

5. Agent Workflow (src/helia/agent/):

   • Graph Architecture: Implements RISEN pattern (Extract -> Map -> Score) using LangGraph in src/helia/agent/graph.py.
   • State: ClinicalState (in state.py) manages transcript, scores, and execution status.
   • Nodes: Specialized logic in src/helia/agent/nodes/ (assessment, persistence).
   • Execution: Run benchmarks via python -m helia.agent.runner <run_id>.

Development Standards

• Environment: Requires OPENAI_API_KEY and MongoDB credentials.
• Configuration: managed via Pydantic models in src/helia/configuration.py.
• Python: Uses implicit namespace packages. __init__.py files may be missing by design in some subdirectories.
• Code Style: Follows PEP 8. Enforced via ruff.
• Security: Do not commit secrets. Avoid hardcoding model parameters; use configuration injection to support the comparative benchmark (Tiers 1-3).