Timbre Backend

Voice-based Parkinson's and depression screening from a 60-second ElevenLabs-guided conversation.

---

Ownership Map

Directory	Owner	Contract
app/extraction/	Jishnuu	Contract C → Contract A
app/calibration/	Varshith	Contract A → Contract B
app/api/	Shared	HTTP layer
app/schemas/	Shared	Pydantic API boundary
app/interpretation/	Shared	Claude API wrapper
contracts.py	READ-ONLY	Source of truth for all data shapes

Rule: Neither developer edits the other's directory. contracts.py is never modified.

---

Contracts Are the Source of Truth

1. contracts.py defines the exact shape of every inter-pipeline message.
2. Both pipelines import from contracts.py — do not duplicate contract definitions elsewhere.
3. When in doubt about a feature name, unit, or field shape, check contracts.py first.

---

Prerequisites

# ffmpeg is required for browser audio transcoding (webm → wav)
brew install ffmpeg    # macOS
# sudo apt install ffmpeg  # Ubuntu/Debian

Running the Server

# Install dependencies
pip install -r requirements.txt

# Start the server (reload enabled)
python run.py

# Or directly with uvicorn
uvicorn app.main:app --reload

The API will be available at http://localhost:8000.
Interactive docs: http://localhost:8000/docs

---

Running the Smoke Test

python scripts/smoke_test.py

This imports both pipelines, runs a mock Contract A through calibration, and prints the result shape. It must pass before either developer writes any real logic.

---

Key Endpoints

Method	Path	Description
GET	/health	Health check
POST	/assessment	Full pipeline (add ?mock=true to skip extraction)
GET	/longitudinal/{profile}	Simulated longitudinal data
POST	/voice-capsule/clone	Voice clone stub

---

Development Workflow

1. Varshith: use ?mock=true on /assessment to test calibration before Jishnuu's extraction lands.
2. Jishnuu: implement app/extraction/pipeline.py::run_extraction_pipeline to replace the mock return.
3. Integration: remove the mock fallback from app/api/assessment.py once both pipelines are wired.