# 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"`
-   **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:

1.  **Ingestion** (`src/helia/ingestion/`):
    -   Parses clinical interview transcripts (e.g., DAIC-WOZ dataset).
    -   Standardizes raw text/audio into `Utterance` objects.

2.  **Analysis & Enrichment** (`src/helia/analysis/`):
    -   **MetadataExtractor**: Enriches utterances with sentiment, tone, and speech acts.
    -   **Model Agnostic**: Designed to swap backend LLMs (OpenAI vs. Local/Quantized models).

3.  **Assessment** (`src/helia/assessment/`):
    -   Implements clinical logic for standard instruments (e.g., PHQ-8).
    -   Maps unstructured dialogue to structured clinical scores.

4.  **Persistence Layer** (`src/helia/db.py`):
    -   **Document-Based Storage**: Uses MongoDB with Beanie (ODM).
    -   **Core Model**: `AssessmentResult` (in `src/helia/assessment/schema.py`) acts as the single source of truth for experimental results.
    -   **Data Capture**: Stores the full context of each run:
        -   **Configuration**: Model version, prompts, temperature (critical for comparing tiers).
        -   **Evidence**: Specific quotes and reasoning supporting each PHQ-8 score.
        -   **Outcome**: Final diagnosis and total scores.

5.  **Agent Workflow** (`src/helia/agent/`):
    -   Built with **LangGraph**.
    -   **Router Pattern**: Decides when to call specific tools (search, scoring).
    -   **Tools**: Clinical scoring utilities, Document retrieval.

## 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).