System Architecture
Two services, two Kubernetes nodes, no cloud dependency for inference. Every component is designed for observability, auditability, and graceful degradation.
Data Flow
1. Session Initiation
A request arrives at Nexi (port 8000). Nexi calls XNCH to validate the auth token, resolve the actor, and create a session context with rate-limit enforcement and KV-cache dedup.
2. Context Assembly
Nexi queries XNCH memory for relevant episodes, learned patterns, and policy references. The 4-layer memory system retrieves sensory signals, working memory, episodic history, and graph relationships.
3. Option Generation & Filtering
Nexi generates candidate actions via LiteLLM (with fallback chain). Each option is sent to XNCH for parallel dry-run policy evaluation. BLOCKed options are dropped; MODIFY verdicts alter the action spec.
4. Scoring & Selection
Surviving options receive a weighted composite score — policy alignment, expected outcome, risk, and context fit. The highest-scoring option is selected unless confidence is too low (triggers escalation).
5. Authoritative Verdict
The selected action is submitted to XNCH for binding re-evaluation. If allowed, XNCH issues a signed JWT execution token. BLOCK verdicts are written to the immutable decision ledger.
6. Execution & Outcome
The signed payload is dispatched to the execution runner. On completion, the outcome is sent back through XNCH, which computes a prediction delta and triggers the next learning cycle if needed.
Design Principles
Graceful Degradation
Every component has a fallback. If vLLM is down, LiteLLM routes to a secondary model, then llama.cpp, then rule-based templates. No single point of failure stops the system.
Observability by Default
Every LLM call, policy evaluation, and verdict is traced via Langfuse. System events are written to a JSONL audit file. The decision ledger is append-only and immutable.
State Versioning
Every state change increments a version counter. XNCH and Nexi verify state version alignment before proceeding. Stale state is detected and rejected.
Deployment
Two physical nodes, Kubernetes, no cloud dependency for inference. Full deployment in under 30 commands.
Memory Node (i7)
kubectl label node i7-node role=memory
Inference Node (i9)
kubectl label node i9-node role=inference