Refactor assessment module and update dependencies; remove unused extractor and graph loader files

README.md

@@ -1,20 +1,27 @@
 # Helia
 
-Agentic Interview Framework for ingesting, analyzing, and querying transcript data.
+**A Modular Agent Framework for Therapeutic Interview Analysis**
+
+This project is the core implementation for the Bachelor Thesis: *"Comparing Local, Self-Hosted, and Cloud LLM Deployments for Therapeutic Interview Analysis"*.
+
+## Project Context
+
+Helia aims to bridge the gap between AI and mental healthcare by automating the analysis of diagnostic interviews. Specifically, it tests whether **local, privacy-first LLMs** can match the performance of cloud-based models when mapping therapy transcripts to standardized **PHQ-8** (Patient Health Questionnaire) scores.
 
 ## Project Structure
 
 ```
 src/helia/
 ├── agent/
-│   └── workflow.py      # LangGraph agent workflow
+│   └── workflow.py      # LangGraph agent & router
 ├── analysis/
-│   └── extractor.py     # LLM metadata extraction
-├── graph/
-│   ├── loader.py        # Neo4j data loading
-│   └── schema.py        # Pydantic graph models
+│   └── extractor.py     # Metadata extraction (LLM-agnostic)
+├── assessment/
+│   ├── core.py          # Clinical assessment logic (PHQ-8)
+│   └── schema.py        # Data models (AssessmentResult, PHQ8Item)
 ├── ingestion/
-│   └── parser.py        # Transcript parsing logic
+│   └── parser.py        # Transcript parsing (DAIC-WOZ support)
+├── db.py                # MongoDB persistence layer
 └── main.py              # CLI entry point
 ```
 
@@ -23,90 +30,59 @@ src/helia/
 ```mermaid
 graph TD
     A[Transcript File<br/>TSV/TXT] -->|TranscriptParser| B(Utterance Objects)
-    B -->|MetadataExtractor<br/>+ OpenAI LLM| C(Enriched UtteranceNodes)
-    C -->|GraphLoader| D[(Neo4j Database)]
-    E[User Question] -->|LangGraph Agent| F{Router}
-    F -->|Graph Tool| D
-    F -->|Vector Tool| G[(Vector Store)]
-    D --> H[Context]
-    G --> H
-    H -->|Synthesizer| I[Answer]
+    B -->|MetadataExtractor<br/>+ LLM| C(Enriched Utterances)
+    C -->|Assessment Engine<br/>+ Clinical Logic| D(PHQ-8 Scores & Evidence)
+    D -->|Persistence Layer| E[(MongoDB / Beanie)]
+
+    U[User Query] -->|LangGraph Agent| R{Router}
+    R -->|Assessment Tool| D
+    R -->|Search Tool| E
 ```
 
-1. **Ingestion**: `TranscriptParser` reads TSV/txt files into `Utterance` objects.
-2. **Analysis**: `MetadataExtractor` enriches utterances with sentiment and tone using LLMs.
-3. **Graph**: `GraphLoader` pushes nodes and relationships to Neo4j database.
-4. **Agent**: ReAct workflow queries graph/vector data to answer user questions.
+1.  **Ingestion**: `TranscriptParser` reads clinical interview files (e.g., DAIC-WOZ).
+2.  **Analysis**: `MetadataExtractor` enriches data with sentiment/tone using interchangeable LLMs.
+3.  **Assessment**: The core engine maps dialogue to clinical criteria (PHQ-8), generating scores and citing evidence.
+4.  **Persistence**: Results are stored as structured `AssessmentResult` documents in MongoDB for analysis and benchmarking.
 
 ## Implemented Features
 
-- Parse DAIC-WOZ transcripts and simple text formats.
-- Extract metadata (sentiment, tone, speech acts) via OpenAI.
-- Load `Utterance` and `Speaker` nodes into Neo4j.
-- Run basic LangGraph agent with planner and router.
+-   **Modular LLM Backend**: designed to switch between Cloud (OpenAI) and Local models (Tier 1-3 comparative benchmark).
+-   **Clinical Parsing**: Native support for DAIC-WOZ transcript formats.
+-   **Structured Assessment**: Maps unstructured conversation to validatable PHQ-8 scores.
+-   **Document Persistence**: Stores full experimental context (config + evidence + scores) in MongoDB using Beanie.
 
 ## Roadmap
 
-- Add robust error handling for LLM API failures.
-- Implement real `graph_tool` and `vector_tool` logic.
-- Enhance agent planning capabilities.
-- Add comprehensive test suite.
+-   [ ] **Comparative Benchmark**: Run full evaluation across Local vs. Cloud tiers.
+-   [ ] **Vector Search**: Implement semantic search over transcript evidence.
+-   [ ] **Test Suite**: Add comprehensive tests for the assessment logic.
 
 ## Installation
 
 Install the package using `uv`.
 
 ```sh
-uv pip install helia
+uv sync
 ```
 
 ## Quick Start
 
-Run the agent directly from the command line.
+1.  **Environment Setup**:
+    ```sh
+    export OPENAI_API_KEY=sk-...
+    # Ensure MongoDB is running (e.g., via Docker)
+    ```
 
-```sh
-export OPENAI_API_KEY=sk-...
-export NEO4J_URI=bolt://localhost:7687
-export NEO4J_PASSWORD=password
+2.  **Run an Assessment**:
+    ```sh
+    python -m helia.main "assess --input data/transcript.tsv"
+    ```
 
-python -m helia.main "How many interruptions occurred?"
-```
+## Development
 
-## Usage
-
-Parse a transcript file programmatically.
-
-```python
-from helia.ingestion.parser import TranscriptParser
-from pathlib import Path
-
-parser = TranscriptParser()
-utterances = parser.parse(Path("transcript.tsv"))
-```
-
-Extract metadata from utterances.
-
-```python
-from helia.analysis.extractor import MetadataExtractor
-
-extractor = MetadataExtractor()
-nodes = extractor.extract(utterances)
-```
-
-Load data into Neo4j.
-
-```python
-from helia.graph.loader import GraphLoader
-
-loader = GraphLoader()
-loader.connect()
-loader.load_utterances(nodes)
-loader.close()
-```
-
-## Contributing
-
-Fork the project and submit a pull request.
+-   **Linting**: `uv run ruff check .`
+-   **Formatting**: `uv run ruff format .`
+-   **Type Checking**: `uv run pyrefly`
 
 ## License