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.

The Protean is built on four ideas. Together they form a posture toward AI systems that few platforms hold consistently.

​
1. Local-first

Every capability runs offline on a developer’s machine before it runs in cloud. Cloud is a deploy target, not a separate codebase. Why: developer feedback loops, privacy of unfinished prompts, ability to demo on a plane. Implication: every dependency must have an offline path (LLM cassettes, local Mongo, embedded Phoenix, in-memory flag store).

​
2. Deterministic

Same input + same seed + same prompt cassette = same trace. Every run is a first-class entity (run_id, seed, cassette_id, events[]) with full lineage. Why: debugging an AI run is impossible without reproducibility. Tests need it. Eval needs it. Customer support needs it. Implication: no Date.now(), Math.random(), or raw fetch outside @protean/runtime’s wrappers. The replay gate fails the build if anyone smuggles non-determinism in.

​
3. Replayable

Runs persist their event log. protean replay <run_id> re-runs the agent verbatim against the recorded cassette and asserts the event sequence matches byte-for-byte. Why: turns a “doesn’t reproduce” bug into a working test in seconds. Implication: the event log is the source of truth, not in-memory state. SDK + UI + CLI all consume the same event stream.

​
4. Streaming-first

SSE/WS from the runtime up through SDK, UI, and CLI. Partial results from token 1. Why: AI UX is a streaming UX; “wait then render” feels broken. Implication: every endpoint that produces an LLM response is SSE; the SDK exposes async iterators; the CLI uses pi-tui to render incrementally.
These are not aspirations. They are non-negotiables. If a proposal violates one, either the proposal changes or the principle is amended via ADR — and amending takes a serious bar. The long-form version (with worked examples per principle) lives at docs/execution-philosophy.md in the repo. ADR-0010 captures the formal commitment.