Engineering notes / 01 — Open-source lab
Spectra
An agent that proposes. A system that verifies.
A bounded AI investigator with typed tools, structured proposals, policy evaluations, and human-approved execution. Built with Python, Go, and React.
- Python
- Go
- React
- TypeScript
- PostgreSQL
- SQLite
- Docker
Why it matters for AI engineering
This project connects model integration to the engineering around it: constrained tool use, structured outputs, abstention, policy evaluations, human approval, traces, and recoverable side effects.
The engineering problem
An LLM proposal is not permission to act. Spectra separates investigation from policy and execution: the agent gathers evidence through bounded tools, the backend validates the proposal, and a human approves sensitive actions. Durable workers then handle retries and the crash-after-action failure window.
Follow the request.
- 01
Bounded investigation
2 tenant-bound tools, 4-step budget, structured proposal
- 02
Policy & approval
Validate target and evidence; require approver role
- 03
Durable queue
Transactional jobs, fenced leases, bounded retries
- 04
Execute & reconcile
Lookup external action, verify effect, record timeline
02 / Design decisions
Where the architecture earns its keep.
Make recovery part of the workflow
Stable external action keys and provider lookup allow a replacement worker to reconcile an existing effect. Fenced leases and heartbeats coordinate ownership; retries are bounded and jittered.
Constrain agent authority
The optional LLM adapter gets two typed, tenant-bound read tools and a four-step budget. Malformed output, repeated tools, missing evidence, or exhausted budgets lead to abstention. Independent policy checks and human approval govern sensitive actions.
Leave an inspectable trail
Persisted execution timelines expose the workflow in React. Application events support per-run hash-chain verification, with Prometheus metrics and optional API tracing for operational visibility.
03 / Verification & scope
Failure is part of the specification.
The documented lab run passed 30 synthetic policy/investigation contracts, plus six HTTP scenarios covering benign alerts, abstention, injected instructions, provider outages, and crash recovery. Scripted model responses exercise the LLM adapter. The crash scenario verifies two integration attempts but one external effect; these are system checks, not a model-accuracy benchmark.