How ahrane-m/ygc works
Purpose and Entry Point
This is a local medical-document pipeline: it extracts prescriptions, lab reports, and discharge summaries into a patient timeline, identifies safety concerns, indexes facts for retrieval, and answers patient-scoped questions. The runtime entry point is FastAPI in api.py, served with uvicorn api:app; application routes are under /api/v1/.
HTTP Orchestration
api.py owns request validation, patient-key normalization, multipart uploads, error mapping, and calls into extraction, retrieval, and conversations. Upload is the central write workflow: it accepts supported document images/PDFs, merges them with existing patient documents, rebuilds derived records, then attempts reindexing. Timeline and safety outputs remain available if vector indexing fails.
• api.py
• README.md
Extraction and Structured Clinical Timeline
medical_extractor.py converts PDF/image documents into structured visit records, including medications, labs, allergies, notes, confidence, and source metadata. It combines newly extracted and previously saved patient documents into a timeline with medication/lab histories and known allergies. This is the authoritative structured-data boundary before downstream safety analysis and retrieval.
• medical_extractor.py
• docs/medical_extractor.md
• docs/pipeline.md
Safety Cross-Checking and Persistence
The extractor stage cross-checks the consolidated timeline for drug interactions, duplicate prescriptions, conflicting dosages, and allergy conflicts, producing an overall recommendation. Patient documents and reports are persisted locally as patient_docs_*.json and patient_report_*.json; these files are unauthenticated local storage and form the durable state for timeline and cross-check reads.
• medical_extractor.py
• docs/pipeline.md
• .gitignore
Retrieval-Augmented Single-Shot Q&A
retrieval.py transforms timeline and safety data into typed chunks, embeds them through OpenAI, and stores patient-isolated collections in persistent Chroma at ./chroma_db. For /qa, it retrieves the top matching chunks and generates a grounded answer with confidence, provenance, and a professional-consult recommendation. Retrieval/indexing depends on external OpenAI embedding and chat services and can fail independently of extraction.
• retrieval.py
• docs/retrieval.md
• inspect_chroma.py
Stateful Multi-Turn Conversations
conversation.py adds per-patient, server-memory sessions above retrieval. Each follow-up is rewritten into a standalone query using conversation context, then passed through retrieval and safety-aware answer generation. Full transcripts are retained only in process memory and are lost on API restart; session lifecycle is exposed through create, message, fetch, and delete endpoints.
• conversation.py
• api.py
• docs/retrieval.md
Runtime and Operational Boundaries
The application runs as Python/FastAPI with Uvicorn. Document parsing uses PDF/image tooling; Chroma provides local persistent vector storage; OpenAI requires OPENAI_API_KEY from .env. inspect_chroma.py is a read-only operational CLI for examining indexed patient chunks without OpenAI calls or store mutation.
• api.py
• inspect_chroma.py
• .env
Components 13
HTTP API
- Patient/API client
- FastAPI routes · Validates requests and coordinates upload, timeline, safety, Q&A, and sessions.
api.py
Clinical pipeline
- Medical documents
- Clinical extractor · Builds the authoritative patient timeline from new and saved documents.
medical_extractor.py - Safety cross-check · Finds interactions, duplicates, dosage conflicts, and allergy conflicts.
medical_extractor.py
Retrieval and answers
- Conversation service · Rewrites follow-ups with session context before retrieval.
conversation.py - Typed chunk builder · Transforms timeline and safety facts into retrieval chunks.
retrieval.py - Grounded Q&A · Retrieves patient-scoped evidence and returns answer, confidence, and provenance.
retrieval.py
Local state
- Patient JSON records · Unauthenticated local documents and reports used for timeline and safety reads.
- Session transcripts · Per-patient sessions are lost when the API process restarts.
conversation.py - Chroma collections · Patient-isolated local vector collections at ./chroma_db.
retrieval.py - Index inspection CLI · Examines indexed patient chunks without OpenAI calls or mutations.
inspect_chroma.py
Other components
- OpenAI services · Indexing and generated answers require OPENAI_API_KEY.
Connections 20
- Patient/API client → FastAPI routes: HTTP /api/v1
- FastAPI routes → Medical documents: accepts uploads
- Medical documents → Clinical extractor: parse PDF/images
- Patient JSON records → Clinical extractor: merge prior documents
- Clinical extractor → Patient JSON records: persist documents and reports
- Clinical extractor → Safety cross-check: consolidated timeline
- Safety cross-check → Patient JSON records: persist safety report
- FastAPI routes → Clinical extractor: upload and timeline workflow
- FastAPI routes → Typed chunk builder: attempt reindex after upload
- Clinical extractor → Typed chunk builder: timeline facts
- Safety cross-check → Typed chunk builder: safety facts
- Typed chunk builder → OpenAI services: embed chunks
- Typed chunk builder → Chroma collections: store vectors by patient
- FastAPI routes → Grounded Q&A: /qa
- Grounded Q&A → Chroma collections: retrieve top chunks
- Grounded Q&A → OpenAI services: grounded answer generation
- FastAPI routes → Conversation service: session endpoints
- Conversation service → Session transcripts: read/write transcript
- Conversation service → Grounded Q&A: standalone follow-up query
- Index inspection CLI → Chroma collections: read-only inspection