Installation

Requirements, environment variables, and project structure.

Requirements

Python 3.10 or later
pip
Git (for baseline version control)

Install

pip install spooled-ai

The package is distributed as spooled-ai on PyPI. In your code, import it as import spooled. The CLI command is spooled. For framework integrations:

pip install spooled-ai[integrations]

Development install

For contributing or local development, clone the repo and install in editable mode:

pip install -e ".[dev]"

Environment variables

All configuration is via environment variables. None are required for local usage.

Variable	Default	Description
SPOOLED_AGENT_ID	"default"	Agent identifier (fallback if not passed to init())
SPOOLED_BACKEND_URL	""	Backend API endpoint. Empty = local-only mode
SPOOLED_API_KEY	(none)	Pro license key for CI automation and content-blind signals
SPOOLED_LOCAL_STORAGE	"true"	Store traces locally in .spooled/traces/
SPOOLED_SAMPLE_RATE	1.0	Fraction of runs to record (0.0–1.0)
SPOOLED_AGENT_TAGS	""	Comma-separated tags for fleet grouping
SPOOLED_FINGERPRINT_MODE	"sequence"	"sequence" (default, order-sensitive) or "structural" (order-insensitive)
SPOOLED_BASELINE_WINDOW_SIZE	10	Successful runs to keep per intent (1–100)
SPOOLED_CORRELATION_CONTEXT	(none)	JSON string for multi-agent session correlation

Project structure

After initialization, your project will have:

.spooled/
├── traces/              # Raw execution traces (JSONL)
│   ├── agent-runid.jsonl
│   └── baselines/       # Generated baseline files
│       └── agent.json
├── ci-history/          # CI comparison history
baselines/               # Git-committed baselines
spooled-policy.yml       # Policy rules

Verify installation

spooled doctor

This checks your Python version, SDK installation, trace directory, and connectivity.