Civitas System Guide
A practical engineering reference for the product path from citizen report to a reviewed municipal recommendation.
Operating Principle: Evidence Over Direct Instruction
Civitas treats incoming citizen reports as evidence that requires interpretation, rather than raw instructions that automatically trigger municipal actions. It preserves the vital boundary between what a resident reported, what media appears to show, context retrieved from GIS systems or city policies, and conclusions reached by deterministic tools or agents.
Observable evidence, retrieved knowledge, model outputs, inferences, and human decisions are kept strictly distinct in every contract, database record, and UI surface.
- Preserve contradictory claims across multiple citizen reports instead of silently overwriting them.
- Expose model uncertainty explicitly rather than fabricating high confidence.
- Enforce human approval checkpoints for high-impact routing, work-order creation, and ticket closure.
Decision Lifecycle & Golden Slice
A citizen report undergoes a multi-stage deterministic pipeline. Disparate reports are clustered into shared incidents via PostGIS spatial indexing. ML models extract visual features, policy playbooks are retrieved via hybrid grounding, and a critic node verifies the draft work order before pausing for human supervisor authorization.
Citizen Report (Text + Media + GPS)
│
▼
[01 Intake Context Normalization]
│
▼
[02 Multimodal ML & Spatial Clustering] ──► (DBSCAN + CLIP Zero-Shot)
│
▼
[03 Policy Grounding & Retrieval] ──► (PostGIS + Playbooks)
│
▼
[04 Work Order Synthesis & Routing]
│
▼
[05 Critic Node Validation] ──► (Check Constraints)
│
▼
[06 Human Supervisor Gate] ──► (Approve / Edit / Reroute / Reject)Typed Shared Contracts
Public API envelopes, ML inference payloads, LangGraph checkpoint state, knowledge evidence, and human review actions are strictly schema-validated with Pydantic and TypeScript. Typed contracts make failures immediately visible at component boundaries instead of allowing corrupted data to silently influence downstream municipal decisions.
Traceability & Observability
Every node execution records a unique trace identifier, model name, token usage metrics, latency, retry counts, validation state, and referenced policy IDs. Secrets, authorization headers, and unnecessary raw private resident data are never persisted into operational trace logs.