Quickstart

Get Spooled running in under 5 minutes. You'll install the SDK, run a demo agent, generate a baseline, and see behavioral comparison in action.

1. Install

pip install spooled-ai

Requires Python 3.10+. The package is distributed as spooled-ai on PyPI. In your code, import it as spooled.

2. Initialize a project

spooled init project --with-demo

This creates:

• A .spooled/ directory for traces and baselines
• A spooled-policy.yml with sensible defaults
• A demo_agent.py script you can run immediately
• A baselines/ directory with an initial baseline
• A .github/workflows/ CI workflow for behavioral testing

3. Verify your setup

spooled doctor

Checks your Python version, SDK installation, trace directory, baseline files, and policy configuration. Run this anytime something seems off.

4. Run the demo agent

python demo_agent.py

This runs a simulated agent with LLM calls and tool calls. Spooled captures the execution trace automatically. Run it at least 3 times to build up enough data for a stable baseline.

5. View the trace

spooled list traces
spooled view trace <run-id>

List your traces first, then view one by its run ID. You'll see the full interaction sequence with timing, types, and the hash chain.

6. Generate a baseline

spooled ci update-baseline \
    --from .spooled/traces/ \
    --out baselines/ \
    --min-runs 3

This aggregates your traces into a behavioral baseline. The --min-runs 3 flag ensures each intent has enough data for stable statistical bounds. Commit the baselines to git.

7. Compare against baseline

spooled ci compare \
    .spooled/traces/<latest-trace>.jsonl \
    --baseline baselines/

This compares the latest trace against the baseline. You'll see a result like:

  demo_agent: MATCH
  Spooled Score: 100/100 (A)
  Policy: PASSED

  RESULT: PASS ✓