---
status: active
owner: platform
last_reviewed: 2026-10-11
supersedes: [docs-design-tech-stack-v1]
---
# Studio Engine — Tech Stack (living)

<!-- wiki:featured -->

**Component inventory SSOT:** [`docs/tech-stack/inventory.yaml`](../tech-stack/inventory.yaml) → `/wiki/` (Layers · Technology).  
This file is **engine narrative only** — do not duplicate inventory tables here. Runtime still wins versions at generate time.

**Track version:** see `VERSION` (2.2.0) · **Audited:** 2026-10-13

### Roadmap

- ✅ v2.0.0 "Nexus" — CDS Hooks + Nous ANDI + Vast warm (18 UDS routes)
- ✅ v2.1.0 "Nexus" — foundation pack wired to UDS (11 new Oracle routes + vLLM auth fix)
- ✅ v2.2.0 "Nexus" — science pack wired to UDS (`science_routes.py`)

**Current:** v2.2.0 "Nexus" — science pack UDS routes live in `science_routes.py`

## Code surfaces (this repo)

| Component | Path | Role (observed) |
|-----------|------|-----------------|
| LLM brain | `platform/shared/llm_brain.py` | Product LLM entrypoint |
| LLM policy | `platform/shared/llm_policy.py` | Task-type / routing policy |
| ANDI | `platform/andi/` (`ANDI.md`, `agents/`, `jev_client.py`) | Intelligence / agent layer |
| ANDI foundation | `docs/studio-engine/FOUNDATION_BASELINE.md` + `TECH_FOUNDATION.md` + `andi312` | Baseline freeze + science/PQC base; wire at product time |
| Job worker | `platform/jobs/` + `studio-job-worker.service` | Async queue worker |
| MCP server | `platform/shared/mcp/server.py` + `studio-mcp.service` | Studio MCP |
| Studio API | `fastapi.service` → `:8000` | Shared FastAPI |

## Python packages (host `pip list`, 2026-09-29)

| Package | Version |
|---------|---------|
| fastapi | 0.141.1 |
| uvicorn | 0.52.3 |
| pydantic | 2.13.4 |
| langgraph | 1.2.11 |
| openai | 3.3.0 |
| anthropic | 1.2.0 |
| unclecode-litellm | 1.81.13 |
| redis | 8.1.0 |
| qdrant-client | 1.19.0 |
| presidio_analyzer | 2.2.364 |
| presidio_anonymizer | 2.2.364 |
| ragas | 0.2.15 |
| lightrag-hku | 1.5.6 |
| temporalio | 1.32.0 |

## Inference gateway (runtime)

| Service | Evidence | Endpoint |
|---------|----------|----------|
| LiteLLM | Docker `studio-litellm` (`ghcr.io/berriai/litellm:main-latest`) | host `:4000` |

## Not present in this audit

- `phi4-mini` Ollama model (not in `ollama` tags)
- XGrammar package (not in `pip list`)

---

## ANDI Architecture — Production Pipeline

### Pipeline Execution Order

1. **Validation Boundary**
   - `fhir.resources` — FHIR R4 structural validation
   - `pyx12` — X12 EDI 270/271/278/835/837 validation
   - `hl7apy` — HL7 v2 legacy message parsing
   - **Rule:** no raw payload reaches symbolic layer without passing validation boundary first

2. **LLM Sensor Layer (Machine 2 — Vast GPU)**
   - ClinicalBERT — fast token-level NER (<50ms, CPU)
   - SapBERT — clinical synonym → SNOMED/LOINC normalization via onnxruntime (<10ms)
   - Qwen3.5-4B-GPTQ-MTP via vLLM (served id `qwen3-4b`) — clinical NLP, structured output, tool calling
   - **Rule:** LLMs extract facts only, never reason

3. **Symbolic Verification (Machine 1 — Oracle ARM64)**
   - Z3 — constraint satisfaction, formal proof
   - Clingo — defeasible logic, payer rule trees
   - Both run via Unix Domain Socket warm process at `/tmp/andi_causal.sock` (<2ms overhead)
   - **Rule:** verify logical consistency before Jev

4. **Jev — Domain Reasoning Engine (Core)**
   - **Location:** `platform/andi/jev_client.py`
   - **Role:** Orchestration backbone and arbiter of truth
   - **Operations:**
     - Queries pyoxigraph via SPARQL (clinical ontologies)
     - Queries Kùzu via Cypher (payer rules, claims chains)
     - Computes domain-specific factor attributions
     - Establishes baseline confidence scores
     - Integrates into decision contract
   - **Properties:**
     - Outcome-driven — learns from ground truth weekly
     - Interpretable — factors auditable by domain experts
     - Transfers across domains without retraining
     - Works with small N — no massive dataset needed
     - Improves monotonically as outcomes accumulate
   - **Rule:** Jev is proprietary — never replace with open source tools, only complement

5. **Science Pack Coprocessors (Parallel after Jev)**
   - **Scallop** — probabilistic Datalog verification; validates Jev factor combinations against medical rules and billing guidelines; passes soft probabilistic weights into Jev scoring matrices
   - **StatsPAI** — causal confounder adjustment; discovers latent confounders Jev misses; counterfactual Do-Calculus protection against systemic dataset shift
   - **blackjax** — population uncertainty smoothing; refines Jev uncertainty across long timelines via JAX-native GPU MCMC
   - **Venn-Abers** — formal calibration bounds; turns Jev confidence scores into distribution-free statistical guarantees required for CMS audit compliance

6. **Decision Contract Output**

```json
{
  "claim": "string",
  "evidence_tier": "formal|estimated|prior|heuristic",
  "uncertainty": {"type": "", "value": 0.0, "coverage": 0.0},
  "jev_factors": [{"factor": "", "weight": 0.0, "direction": ""}],
  "provenance": {"model": "", "version": "", "training_date": ""},
  "model_version": "sha256"
}
```

7. **Outcome Logging → Weekly Jev Calibration**
   - Every prediction paired with ground truth
   - Weekly batch refit on Vast GPU
   - Brier score + conformal coverage checked
   - Evidence tier promotion gated on N≥100

### Multi-Graph Architecture

Three-database polyglot architecture:

**pyoxigraph (In-Memory RDF, Machine 1):**
- SNOMED CT — 350,000 concepts, 1M+ relationships
- LOINC — 90,000+ lab terms
- RxNorm — drug terminology
- ICD-10, CPT — diagnosis and procedure codes
- Query: SPARQL subsumption (<100ms)
- Jev queries this for ontology factor inputs

**Kùzu (Disk-backed property graph, Machine 1):**
- Payer rules graph
- Claims denial chains
- Provider network graph
- Connects to PyG via zero-copy Apache Arrow
- Query: Cypher traversal (<20ms)
- Jev queries this for structural factor inputs

**DuckDB (Encrypted, Machine 1):**
- Patient PHI graphs (strictly isolated)
- Claims analytics and outcome logs
- Performance metrics
- Cross-graph joins via Arrow zero-copy
- PHI never federates without de-identification

### Science Pack — Full Inventory

## andi312 Environment

**Policy:**
- science packages in `andi312` only
- FastAPI on system Python
- Never import science pack at module level
- Always lazy-import inside functions
- Run andi312 Python from `~` or `/tmp` — never from repo root (`platform/` shadows stdlib)

**Use:** `~/miniforge3/envs/andi312/bin/pip` directly

### Currently Wired (active code imports)

| Package | Version | Where Used |
|---------|---------|-----------|
| z3-solver | 5.1.0 | `prd_verifier.py`, `query_validator.py` |
| clingo | 5.8.2 | `legal_verifier_script.py` |
| pyoxigraph | 0.5.11 | `kg_init.py`, `kg_query.py` |
| oqs/liboqs | 0.16.0.1 | `quantumshield_script.py`, UDS `quantum_shield` |
| dowhy | 0.13.0 | `causal_viability.py` (migrating to statspai) |
| evidently | 0.7.23 | UDS `evidently_monitor` |
| nannyml | 0.13.1 | UDS `nannyml_estimate` |
| mlflow | 3.16.0 | UDS `mlflow_log` |
| shap | 0.52.0 | UDS `shap_explain` |
| pandera | 0.33.1 | UDS `pandera_validate` |
| duckdb | 1.5.5 | UDS `duckdb_query` |
| kuzu | 0.11.3 | UDS `kuzu_query` |
| pymdp | 0.0.1 | UDS `pymdp_policy` (Oracle andi312) |
| tigramite | 5.2.10.1 | UDS `tigramite_pcmci` |
| pyAgrum | 3.1.1 | UDS `pyagrum_infer` |

### Installed — Wire At Product Time

| Package | Version | Role | Machine |
|---------|---------|------|---------|
| numpyro | 0.21.0 | Bayesian model specification | both |
| nutpie | 0.16.11 | Fast Rust NUTS sampler | both |
| jax | 0.11.0 | Hardware-accelerated compute | both |
| mapie | 1.5.0 | Adaptive conformal calibration | both |
| statspai | 1.34.2 | Unified causal inference | both |
| ruptures | 1.1.10 | Change point detection | both |
| onnxruntime | 1.30.0 | Model portability + SapBERT | oracle |

### Removed from andi312 (2026-10-03 audit — no code imports)

| Package | Replaced By | Reason |
|---------|------------|--------|
| econml 0.17.0 | statspai | StatsPAI covers treatment-effect needs |
| CausalPy 0.9.0 | statspai | StatsPAI covers causal workflows |
| causalimpact 0.2.6 | statspai | StatsPAI covers BSTS-style needs |
| crepes 0.9.1 | mapie | MAPIE covers conformal calibration |
| hmmlearn 0.3.3 | pomegranate (Vast) | GPU HMM + missing-data path |

Kept (product layer): `evidently`, `nannyml`, `dowhy`, `mlflow`, `shap`, `pandera`, `pymdp`, `pyAgrum`, `ruptures`, `tigramite`.

### To Install — Healthcare Products

| Package | Machine | Role | Priority |
|---------|---------|------|---------|
| fhir.resources | oracle | FHIR R4 Pydantic v2 validation | P0 |
| pyx12 | oracle | X12 EDI grammar validation | P0 |
| vLLM | vast-gpu | Qwen3.5-4B-GPTQ-MTP serving (id `qwen3-4b`) | P0 |
| hl7apy | oracle | HL7 v2 legacy parsing | P1 |
| SapBERT | oracle | Clinical synonym SNOMED norm | P1 |
| Venn-Abers | oracle | Formal classification calibration | P1 |
| Scallop | vast-gpu | Probabilistic Datalog for Jev | P1 |
| blackjax | vast-gpu | JAX-native GPU MCMC sampler | P1 |
| PyG 2.6+ | vast-gpu | GNN on clinical graphs | P2 |
| PyKEEN | vast-gpu | SNOMED KG embeddings for Jev | P2 |
| Bytewax | oracle | Real-time FHIR R4 streaming | P2 |
| pomegranate | vast-gpu | GPU HMM patient trajectories | P2 |
| OR-Tools | oracle | Quantum-inspired scheduling | P3 |

### Infrastructure Requirements

Thread limits (Oracle ARM64 4-core):
- `RAYON_NUM_THREADS=2`
- `OMP_NUM_THREADS=2`
- `MKL_NUM_THREADS=2`
- Reserve 2 cores for FastAPI event loop

Unix Domain Socket warm process:
- Location: `/tmp/andi_causal.sock`
- Keeps JAX, Z3, StatsPAI pre-loaded
- Eliminates 350-800ms cold start latency
- Target: <2ms subprocess overhead

stdout guard (all andi312 scripts):
- Redirect non-JSON output to stderr
- Parse only final JSON via `r"(\{.*\})"` with `re.DOTALL`

### Phase 2 — Deferred

| Package | When | Why |
|---------|------|-----|
| Scallop | P1 (promoted) | Jev probabilistic verification |
| gCastle | P3 | Causal structure learning |
| PyReason | skip | Scallop covers this |
| Dirichlet tier | P3 | Dynamic epistemic constitution |

### LLM Layer

| Component | Machine | Role |
|-----------|---------|------|
| Qwen3.5-4B-GPTQ-MTP | vast-gpu | Primary LLM via vLLM (served `qwen3-4b`) |
| ClinicalBERT | oracle | Fast token NER (<50ms CPU) |
| SapBERT | oracle | SNOMED normalization (<10ms) |
| Ollama qwen2.5/qwen3 | oracle | Fallback LLM only |
| LiteLLM | oracle | Routing layer |

LiteLLM routing rules:
- **Machine 1** → ClinicalBERT NER, regex, Pydantic, X12 validation, SNOMED lookup cache
- **Machine 2** → Qwen3 complex NLP, structured output, clinical note summarization