AVIV SHPAKAll work

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.

  1. 01

    Bounded investigation

    2 tenant-bound tools, 4-step budget, structured proposal

  2. 02

    Policy & approval

    Validate target and evidence; require approver role

  3. 03

    Durable queue

    Transactional jobs, fenced leases, bounded retries

  4. 04

    Execute & reconcile

    Lookup external action, verify effect, record timeline

02 / Design decisions

Where the architecture earns its keep.

01

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.

02

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.

03

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.