How karkavelrajaj-coder/pharmaforceiq-clinical-ai-assistant works
Purpose and Entry Points
This repository is a standalone Streamlit clinical-literature retrieval demo. It compares general and medical-tuned embedding models during a conversation, retrieves evidence from Qdrant, synthesizes answers with Anthropic Claude, and verifies citations/numeric claims afterward.
Primary deployment entry point: app.py. Earlier iteration entry points remain in V1/app.py and V2/app.py.
Application Orchestration
app.py owns the Streamlit UI, session/conversation state, sidebar model and provider selectors, secrets validation, and the query lifecycle. It presents source availability transparently: literature retrieval is live; claims, FDA labels, and evidence-document sources are intentionally unconnected.
Relevant paths:
• app.py
• requirements.txt
Input Safety / HIPAA Boundary
Before retrieval, user input passes a two-layer PHI screen. Regex detection blocks known structured identifiers; if it passes, Claude Haiku performs semantic PHI detection for free-text identifiers. API failures are fail-closed, preventing the query from reaching retrieval or synthesis.
This is a privacy boundary between public user input and external Qdrant/Anthropic calls.
Relevant paths:
• app.py
Embedding and Retrieval Stage
The app selects between BAAI/bge-small-en-v1.5 and abhinand/MedEmbed-small-v0.1; Streamlit resource caching keeps loaded models warm across model switches. Query embeddings are sent to Qdrant, whose returned chunks contain document stem, section title, and text.
Retrieval over-fetches candidates and applies per-document caps (MAX_CHUNKS_PER_STEM=2) to avoid a single source dominating the evidence set. The selected chunks are formatted as guideline-style clinical evidence because bibliographic metadata is unavailable.
Relevant paths:
• app.py
• formatter.py
Prompting and Answer Synthesis
Retrieved context and user-selected provider role/type framing are assembled into the clinical system prompt. Anthropic Claude Sonnet produces the final answer using grounded evidence, low-temperature synthesis, and streaming output. Prompt definitions are isolated from UI/retrieval mechanics, allowing production-aligned clinical behavior to evolve independently.
Relevant paths:
• prompts.py
• app.py
Post-Synthesis Verification
After streaming completes, answer text is checked against retrieved data. Citation verification flags author/year-style citations that cannot be supported by the corpus; numeric verification compares stated percentages, ratios, and lab-like values against retrieved chunk text. Results are surfaced in the answer Details area rather than silently modifying the response.
Relevant paths:
• citation_verify.py
• numeric_verify.py
• app.py
Runtimes and External Services
The runtime is Python with Streamlit, deployed locally or on Streamlit Community Cloud. Required secrets configure:
• Qdrant Cloud for vector search (QDRANT_URL, QDRANT_API_KEY)
• Anthropic APIs for Claude Sonnet synthesis and Claude Haiku PHI review (ANTHROPIC_API_KEY)
• Hugging Face-compatible embedding model downloads/caching at runtime
Dependency definitions are in requirements.txt; prior version-specific dependency sets are in V1/requirements.txt and V2/requirements.txt.
Version Layout
The repository root is the current integrated implementation, including verification modules. V1/ and V2/ preserve earlier standalone Streamlit variants; V2/ includes its own prompt module and represents the earlier production-prompt/retrieval-alignment stage.
Relevant paths:
• V1/app.py
• V2/app.py
• V2/prompts.py
Main entry points: app.py Diversified evidence set · citation_verify.py Citation verification · numeric_verify.py Numeric verification · formatter.py Evidence formatter
Components 20
Current application
- Streamlit orchestration · Owns UI, session state, selectors, secrets, and query lifecycle.
app.py - Runtime dependencies
requirements.txt
Privacy boundary
- Structured PHI screen · Blocks known structured identifiers before external calls.
app.py - Semantic PHI review · Fails closed when review fails or identifies free-text PHI.
app.py
Retrieval pipeline
- Embedding model selector · Selects BGE Small or MedEmbed Small.
app.py - Cached embedding models · Keeps downloaded embedding models warm across switches.
app.py - Candidate retrieval · Queries Qdrant for evidence chunks.
app.py - Diversified evidence set · Over-fetches then caps chunks per document stem.
app.py - Evidence formatter · Formats chunks as guideline-style evidence without bibliographic metadata.
formatter.py
Answer and verification
- Clinical prompt definitions
prompts.py - Grounded prompt assembly · Combines evidence with selected provider role and type framing.
app.py - Streaming answer synthesis · Generates low-temperature answers grounded in retrieved evidence.
app.py - Citation verification · Flags author/year citations unsupported by the retrieved corpus.
citation_verify.py - Numeric verification · Compares stated numbers with retrieved chunk text.
numeric_verify.py
External services
- Qdrant Cloud · Configured by QDRANT_URL and QDRANT_API_KEY.
- Anthropic API · Provides Haiku review and Sonnet synthesis.
- Embedding model downloads · Hugging Face-compatible runtime model source.
Earlier variants
- V1 standalone app
V1/app.py - V2 production-aligned variant · Earlier prompt and retrieval-alignment stage.
V2/app.py - V2 prompts
V2/prompts.py
Connections 22
- Runtime dependencies → Streamlit orchestration: defines runtime
- Streamlit orchestration → Structured PHI screen: screens query
- Structured PHI screen → Semantic PHI review: if regex passes
- Semantic PHI review → Embedding model selector: approved query
- Semantic PHI review → Anthropic API: PHI review
- Embedding model selector → Cached embedding models: loads selected model
- Cached embedding models → Embedding model downloads: downloads models
- Cached embedding models → Candidate retrieval: query embedding
- Candidate retrieval → Qdrant Cloud: vector search
- Candidate retrieval → Diversified evidence set: retrieved chunks
- Diversified evidence set → Evidence formatter: capped chunks
- Evidence formatter → Grounded prompt assembly: clinical evidence
- Clinical prompt definitions → Grounded prompt assembly: system prompt
- Grounded prompt assembly → Streaming answer synthesis: grounded request
- Streaming answer synthesis → Anthropic API: Sonnet streaming
- Streaming answer synthesis → Citation verification: completed answer
- Streaming answer synthesis → Numeric verification: completed answer
- Diversified evidence set → Citation verification: evidence corpus
- Diversified evidence set → Numeric verification: evidence corpus
- Citation verification → Streamlit orchestration: Details findings
- Numeric verification → Streamlit orchestration: Details findings
- V2 prompts → V2 production-aligned variant: used by