A Fact-governed agent framework for building deterministic and auditable autonomous systems.
Slater is a Python framework for building state-driven AI agents whose behavior is:
- Deterministic — Given the same facts, agents always make the same transitions
- Inspectable — Every decision is traceable to explicit rules and facts
- Replayable — Complete iteration history enables post-run debugging
- Explainable — Agent behavior is specified declaratively before execution
Instead of writing imperative loops that decide "what to do next," you describe the structure of an agent via an AgentSpec, and Slater executes that structure safely.
Bundle your agent's complete behavior into a single, validated AgentSpec:
fromslater.phasesimportPhaseEnum, PhaseRulefromslater.policiesimportControlPolicy, TransitionPolicyfromslater.proceduresimportProcedureTemplatefromslater.specimportAgentSpecPhase=PhaseEnum.create("START", "PROCESSING", "DONE")
spec=AgentSpec(
name="my-agent",
version="1.0.0",
phases=set(Phase),
control_policy=ControlPolicy(...),
transition_policy=TransitionPolicy(rules=[...], default=Phase.START),
procedures={Phase.START: ProcedureTemplate(...), ...},
)Define agent-specific phases with validation:
fromslater.phasesimportPhaseEnum# Names must be UPPER_SNAKE_CASE, no reserved wordsPhase=PhaseEnum.create(
"NEEDS_CONTEXT",
"READY_TO_CONTINUE",
"TASK_COMPLETE",
)Facts are typed, scoped, and flow through the system with clear semantics:
| Scope | Visibility | Persistence |
|---|---|---|
iteration | Current iteration only | Not persisted |
session | All iterations | Agent lifetime |
persistent | All iterations | Across restarts |
- Cycle detection — Agents fail fast if stuck in the same phase
- Rule validation — Overlapping PhaseRules caught at construction time
- Deterministic transitions — Phase changes derived only from durable facts
Two-file persistence pattern:
{agent_id}.json— Current state snapshot{agent_id}_history.jsonl— Append-only iteration log
| Concept | Purpose |
|---|---|
| Phase | Where the agent is in its lifecycle |
| Fact | A typed piece of knowledge emitted by Actions |
| Action | A unit of work that reads state and emits Facts |
| Procedure | A sequence of Actions executed for a Phase |
| PhaseRule | Declares when to transition between Phases |
| ControlPolicy | Global constraints (completion, failure, pause) |
| TransitionPolicy | Rules for FSM progression |
| AgentSpec | The complete, validated agent definition |
- Python 3.10+
- uv (installed automatically by Makefile)
# Create virtual environment and install dependencies
make venv
# Activate the environmentsource .venv/bin/activate# Run all tests
make tests
# Run unit tests only
make unit-tests
# Run integration tests only
make integration-tests# Show available commands
make help# Export dependencies to requirements.txt
make requirements
# Clean build artifacts
make cleanslater/
├── slater/ # Main package
│ ├── __main__.py # CLI entrypoint
│ ├── controller.py # AgentController (execution engine)
│ ├── phases.py # PhaseEnum factory, PhaseRule
│ ├── policies.py # ControlPolicy, TransitionPolicy
│ ├── procedures.py # ProcedureTemplate
│ ├── spec.py # AgentSpec (declarative specification)
│ ├── state.py # StateStore implementations
│ └── types.py # Fact, Facts, core types
├── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── docs/ # Documentation
│ ├── adr/ # Architecture Decision Records
│ └── user-guide.md
├── pyproject.toml
├── Makefile
└── README.md
- User Guide — Comprehensive guide to designing agents
- ADR-001: Dynamic Phase Enums — PhaseEnum design rationale
MIT