A framework for reducing LLM variance on technical/scientific tasks by routing through deterministic gates and kernels.
- Goal: Ambiguity becomes a first-class outcome (CLARIFY), not a guess
- Non-goals: Replacing LLMs; handling arbitrary domains without validation
- LLMs: propose / extract / format
- Deterministic system: validates / selects / executes / records
Same validated spec → same numeric outputs (D1 determinism)
# Prerequisites
python 3.11+
pip install fastapi uvicorn pyyaml
# Run tests
python tests/test_golden_path.py
# Start gateway
uvicorn gateway.main:app --reload
# Test endpoint
curl -X POST http://localhost:8000/task \
-H "Content-Type: application/json" \
-d '{"user_input": "specific weight of water"}'# Expected: {"status": "clarify", ...}gateway/ # FastAPI entrypoint, structured logging
router/ # Deterministic task classification
validator/ # Gates consuming policies (schema, units, ambiguity)
kernels/ # Deterministic compute units (units, constants)
registry/ # Kernel registry, quantities, reason codes
schemas/ # JSON Schema contracts
policies/ # YAML policy files
docs/ # Architecture, pipelines, determinism docs
tests/ # Golden path integration tests
| File | Purpose |
|---|---|
gateway/main.py | FastAPI routes: /task, /kernel, /registry |
router/classifier.py | Rule-based domain classification |
validator/gates.py | Schema, unit, ambiguity gates |
kernels/units.py | UCUM unit conversion |
kernels/constants.py | Authoritative physical constants |
tests/test_golden_path.py | Regression tests |
- File writes are patch-only and sandboxed (see
docs/FILE_WRITE_POLICY.md) - All requests logged as JSONL for audit
- Gates enforce CLARIFY on ambiguous inputs
# Input: "What is the specific weight of water?"# Router detects:# domain: physics.fluids# ambiguous_terms: ["specific weight"]# Ambiguity gate returns:# decision: CLARIFY# reasons: ["TERM_COLLISION", "DISALLOWED_TERM"]# required_fields: ["specific_weight_disambiguation"]# System asks: "Is 'specific weight' weight density (N/m³) or surface tension (N/m)?"- Implemented: Gateway, router, validator, unit/constants kernels
- In progress: Additional domain kernels
- Next: LLM integration for spec extraction