Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.protean.peerislands.io/llms.txt

Use this file to discover all available pages before exploring further.

A cassette is a JSON file mapping LLM request fingerprints to recorded responses. @protean/llm operates in three modes:
  • live — every call hits the real provider (OpenRouter by default). Tokens cost money. Used in production and during development.
  • record — calls hit the provider, response is saved to tests/cassettes/<id>.json keyed by request hash.
  • replay — calls look up the request hash in the cassette; throw if not found. No network. No cost. Deterministic.

​
Why this shape

LLM tests would be either flaky (live, non-deterministic outputs) or fake (mocked responses that don’t reflect the real provider). Cassettes split the difference: real provider behavior captured once, replayed forever.

​
Authoring

Tests record on first run, replay forever after: 
bun run cassette:record <test-id>     # one-shot, writes the JSON
bun test                              # replays from cassette
Re-record only when the prompt or model intentionally changes. The cassette filename should encode the model so different model versions don’t silently overwrite each other (see replay on seed versioning — same idea).

​
Where they live

tests/cassettes/<test-id>.json next to the test. Don’t hand-edit. ADR-0010 codifies the commitment.