A production-grade, event-driven programmable agent runtime where the runtime owns execution control, not the LLM.
Companion project to nexus-agents.
- Deterministic first — explicit state machines, behavior trees, and utility scoring before any model involvement
- Replayable — every run produces decision traces that can be replayed and inspected
- Typed everything — state, events, actions, goals, anomalies, traces — all typed
- Bounded LLM — model advises, runtime decides. LLM cannot bypass constraints or manage state
- Observable — every decision is traceable, every action is logged, every policy is testable
Constraints → Interrupts → FSM/BT → Utility → Planner → LLM Advisory → Escalation
↑ ↓
└─────────────── Event Bus ◄──── Executor ◄──── Replay ──┘
Working vertical slice — Phases 1-3 complete with 60 passing tests covering the event bus, constraints, FSM, runtime loop, replay, and eval harness.
# Install dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Type check
mypy .
# Lint
ruff check .core/ — typed models, events, state, constraints, runtime loop
policies/ — FSM, behavior trees, utility scoring, planner, recovery
adapters/ — simulation environment, external integrations
executor/ — action execution with timeout, retry, fallback
telemetry/ — structured logging and metrics
replay/ — decision trace persistence and replay
plugins/ — narrow SDK and built-in plugins
llm/ — bounded advisory layer (after deterministic core works)
eval/ — seeded scenarios, regression, adversarial tests
console/ — CLI inspection and replay tooling
This project follows nexus-agents CODING_STANDARDS.md.
See AGENTS.md for non-negotiable architectural rules.
MIT