How lmrgroupai/vmpvt3 works
1. What this repo is
- This is a Dockerized clinical/health decision-support system with a Python backend and a React/Vite frontend.
- The backend appears modular, with multiple “engines” for reasoning, retrieval, rules, monitoring, and domain-specific workflows.
2. User-facing presentation layer
- The interactive UI lives under frontend/src with the main React entrypoint at frontend/src/main.jsx and app shell in frontend/src/App.jsx.
- The built frontend is also checked in under static/, which suggests the Python app can serve precompiled assets directly.
- There are duplicate frontend/frontend/* files, which look like a nested copy from packaging/build history rather than a separate product surface.
3. Backend entrypoints and composition
- The backend has several possible launch paths: start.py, api_server.py, app_full.py, app_minimal.py, and multiple enhanced_api_v3* variants.
- This usually means the system supports different deployment profiles: a minimal API, a fuller orchestration mode, and patched/experimental variants.
- For an architecture diagram, treat these as alternative compositions over the same underlying modules, not separate products.
4. Core orchestration / clinical reasoning layer
- Files like comprehensive_clinical_engine.py, preventive_engine.py, drug_discovery_agent.py, and rag_engine.py indicate the main business logic is split by use case.
- comprehensive_clinical_engine.py is likely the top-level orchestrator that combines multiple reasoning modes into one clinical response.
- preventive_engine.py and drug_discovery_agent.py appear to be specialized sub-engines for narrower workflows.
5. Knowledge and retrieval subsystem
- rag_engine.py, canonical_registry.py, golden_dataset_synonyms.py, and amplify_dataset.py suggest a knowledge-driven system with retrieval and normalization.
- The retrieval path likely maps user input to canonical clinical terms, synonyms, and curated datasets before generating output.
- This is the likely boundary between raw user language and structured medical reasoning.
6. Rules, experts, and ensemble logic
- classical_rules.py, moe_experts.py, pillar_28_module.py, pillar_29_module.py, pillar_30_module.py, ansha_kalpana.py, and avarana_ty_module.py suggest multiple reasoning components are combined, probably via a mixture-of-experts or rule stack.
- The architecture likely uses deterministic rules plus expert modules to complement retrieval-based generation.
- A diagram should show these as internal decision layers feeding the final clinical response, not as independent services unless deployed separately.
7. Model/runtime integration
- rlm_hf.py implies Hugging Face model integration or model-loading utilities.
- enhanced_api_v3_kg_patched.py hints at a knowledge-graph-aware path, so some variants may incorporate structured graph reasoning in addition to text retrieval.
- There is no obvious separate database directory, so much of the “knowledge” likely lives in code, serialized datasets, or embedded resources.
8. Output and response shaping
- output_schema.py likely defines the contract for API responses and structured clinical outputs.
- This is an important architectural boundary: internal reasoning can be complex, but external consumers probably receive a normalized schema from this module.
- If you’re drawing the system, place this right before the API layer returns data to the UI.
9. Quality control and monitoring
- drift_monitor.py indicates the system tracks distribution or performance drift, which is important for ML/LLM-backed clinical tools.
- This suggests a feedback/observability loop separate from the main inference path.
- lazy_patch.py may be a runtime patching or compatibility helper used to stabilize behavior across variants.
10. Deployment and serving
- The root Dockerfile and the Hugging Face Spaces metadata in README.md show the project is meant to run in a containerized environment.
- The static/ bundle and Python entrypoints imply the container likely serves both the API and the compiled UI from one runtime.
- The presence of both requirements.txt and frontend/package.json means the repo has two build/runtime stacks: Python for backend and Node/Vite for frontend.
11. Likely request flow
- User input enters the React UI or directly hits the API server.
- The backend normalizes terminology, consults canonical/synonym datasets, routes the request through rules/RAG/expert modules, then formats the result using the output schema.
- The response is returned to the frontend, while monitoring logic can observe outputs for drift or quality signals.
12. Useful architecture boundaries for a diagram
- Presentation boundary: React app and compiled static assets.
- API boundary: one of the Python server entrypoints.
- Reasoning boundary: clinical engine, preventive engine, drug-discovery agent, rules, and expert modules.
- Knowledge boundary: canonical registry, synonym/dataset modules, RAG, and possible knowledge-graph path.
- Ops boundary: Docker containerization, Hugging Face deployment, and drift monitoring.
Main entry points: comprehensive_clinical_engine.py Clinical Core · api_server.py API Entrypoints · rag_engine.py RAG · moe_experts.py Experts
Components 20
Presentation
User-facing React app and built static assets
- UI Shell · Main interactive frontend shell
frontend/src/App.jsx - Frontend Entry · Frontend bootstrapping entry
frontend/src/main.jsx - Static Bundle · Checked-in compiled frontend assets
static/index.html
API Layer
Python server entrypoints and response shaping
- API Entrypoints · Alternative backend launch paths and deployment profiles
api_server.py - Response Schema · Structured clinical output contract
output_schema.py
Clinical Reasoning
Orchestration, rules, experts, and specialty engines
- Clinical Core · Top-level clinical reasoning coordinator
comprehensive_clinical_engine.py - Preventive Flow · Preventive or screening-oriented reasoning path
preventive_engine.py - Drug Agent · Drug-oriented workflow and reasoning
drug_discovery_agent.py - Rules · Classical rule-based decision layer
classical_rules.py - Experts · Expert routing and ensemble decision layer
moe_experts.py - Pillar Modules · Representative pillar-style specialist modules
pillar_28_module.py - Specialists · Additional named specialist reasoning modules
ansha_kalpana.py
Knowledge Layer
Retrieval, canonicalization, datasets, and model runtime
- RAG · Retrieval-augmented reasoning and grounding
rag_engine.py - Canonical Terms · Terminology normalization and canonical mapping
canonical_registry.py - Synonyms · Synonym and dataset normalization resources
golden_dataset_synonyms.py - HF Runtime · Hugging Face model loading and runtime utilities
rlm_hf.py - KG Variant · Knowledge-graph-aware API composition variant
enhanced_api_v3_kg_patched.py
Operations
Containerization, monitoring, and runtime patching
- Drift Monitor · Quality and distribution drift tracking
drift_monitor.py - Runtime Patch · Compatibility or stabilization patch layer
lazy_patch.py - Docker · Container build and serving environment
Dockerfile
Connections 21
- Frontend Entry → UI Shell: boots · Frontend entry mounts the app shell
- UI Shell → API Entrypoints: calls API · UI sends user requests to backend endpoints
- Static Bundle → UI Shell: serves UI · Prebuilt assets provide the same UI surface
- API Entrypoints → Clinical Core: orchestrates · Server routes requests into the clinical core
- API Entrypoints → KG Variant: alt composition · Variant backend composition path
- Clinical Core → RAG: retrieves · Core reasoning grounds responses through retrieval
- Clinical Core → Rules: applies · Deterministic rules inform final decisions
- Clinical Core → Experts: routes · Expert ensemble contributes specialized judgments
- Clinical Core → Preventive Flow: specializes · Preventive workflow is invoked when relevant
- Clinical Core → Drug Agent: specializes · Drug workflow is invoked when relevant
- Experts → Pillar Modules: includes · Representative pillar modules participate in the ensemble
- Experts → Specialists: includes · Additional specialist modules contribute
- RAG → Canonical Terms: normalizes · Retrieval maps inputs to canonical clinical terms
- RAG → Synonyms: expands · Synonyms and curated datasets broaden matching
- RAG → HF Runtime: runs on · Model runtime supports retrieval and generation
- Clinical Core → Response Schema: formats · Clinical output is shaped into the response contract
- API Entrypoints → Response Schema: returns · API responses are emitted through the schema boundary
- Clinical Core → Drift Monitor: observes · Outputs and behavior are monitored for drift
- API Entrypoints → Runtime Patch: stabilizes · Patch layer can adjust runtime behavior
- Docker → API Entrypoints: packages · Container bundles backend serving entrypoints
- Docker → Static Bundle: ships · Container can serve checked-in frontend assets