# Cantrip v1.3.3 - Table of Contents

> the extensible, customizable, self-documenting, real-time multi-agent computing environment

## Pages

- [Cantrip](readme.md)
- [Deploying the Familiar](deployment.md)
- [Contributing](contributing.md)
- [Changelog](changelog.md)
- [Architecture](architecture.md)
- [Cantrip in an ACP-Aware Editor — Mounting the Familiar](acp-editor.md)
- [The Spellbook](spellbook.md)
- [Distributed Familiar](distributed-familiar.md)
- [Familiar Eval Harness](eval-harness.md)
- [Observability](observability.md)
- [Public API Guide](public-api.md)
- [Port-Isolated Code Medium](port-isolated-runtime.md)
- [Signer Key Runbook (allow_compile_signers)](signer-key-runbook.md)
- [LICENSE](license.md)

## Modules

- [Cantrip](Cantrip.md): When you call `Cantrip.new/1`, you are constructing a cantrip: a reusable
value that binds an LLM, an identity, and a circle. Cast it with
`Cantrip.cast/3` and one entity is summoned into the circle for one episode;
summon it with `Cantrip.summon/1` and the entity stays alive across many
sends. In the default port code sandbox, a code-medium inhabitant can use the
same `new`/`cast`/`cast_batch` calls to construct and run child cantrips;
Dune circles use injected host closures instead. The shape is shared by
humans and inhabitants, with sandbox-specific affordances.
- [Cantrip.ACP.Diagnostics](Cantrip.ACP.Diagnostics.md): Inspect live ACP sessions and bridges from a remsh attach during operations.
Use this when you need to see what a running stdio ACP session is doing
without restarting the host.
- [Cantrip.ACP.Server](Cantrip.ACP.Server.md): Run this to expose the Familiar to ACP-aware editors over stdio. The
`mix cantrip.familiar --acp` task calls into this server.
- [Cantrip.Circle](Cantrip.Circle.md): Your circle is the bounded place the entity is summoned into. It declares the
medium you think in, the gates you can call, and the wards that constrain
your loop; `Cantrip.new/1` validates that exactly one medium is declared.
- [Cantrip.Cluster](Cantrip.Cluster.md): When you want a Familiar's loom replicated across BEAM nodes, connect the
nodes with normal BEAM tooling first, then use these helpers to wire Mnesia
across them.
- [Cantrip.FakeLLM](Cantrip.FakeLLM.md): Script deterministic LLM responses for tests and evals. Use this when you
need runtime evidence without provider calls; it tests shape, not behavioral
quality.
- [Cantrip.Familiar](Cantrip.Familiar.md): The Familiar is the packaged code-medium coordinator: a cantrip preassembled
with workspace observation gates, code-medium reasoning, durable loom storage,
and a system prompt that teaches composition and medium selection.
- [Cantrip.Familiar.Eval](Cantrip.Familiar.Eval.md): When you change a prompt or a circle and want evidence, you run an eval. This
harness runs Familiar scenarios across seeds, scores each run against rubric
criteria, persists transcripts, and writes a JSON report.
- [Cantrip.Identity](Cantrip.Identity.md): Identity is who the entity is: the system prompt plus model-facing options.
It is bound when the cantrip is constructed and every summoning inherits it.
- [Cantrip.LLM](Cantrip.LLM.md): Implement this behaviour to provide a model backend. The runtime calls
`query/2` with a normalized request and expects a normalized response or an
error tuple with updated provider state.
- [Cantrip.LLM.Response](Cantrip.LLM.Response.md): This is the response shape every LLM provider answer becomes before the
runtime reads it. If you implement `Cantrip.LLM`, prefer returning this shape;
raw provider maps are accepted only when they satisfy the same boundary
contract.
- [Cantrip.Loom](Cantrip.Loom.md): The loom is the entity's autobiography. Every turn you and your children take
is recorded here; with durable storage, the loom persists across summonings
and prior turns are available as `loom.turns`.
- [Cantrip.Loom.Storage](Cantrip.Loom.Storage.md): If you implement this behaviour, you are giving the loom a place to live.
Built-in backends are memory, JSONL, and Mnesia; `load/1` is the optional
rehydration callback that lets a summoning resume from a prior trajectory.
- [Cantrip.Medium](Cantrip.Medium.md): A medium determines the shape of thought inside the circle. Implement this
behaviour when conversation, code, and bash do not fit the natural surface of
the work.
- [Cantrip.WardPolicy](Cantrip.WardPolicy.md): Wards are the policy that bounds your loop. The runtime resolves them here:
numeric and boolean wards compose by tightening, while passthrough ward data
remains explicit policy for the gate or medium that enforces it.

## Mix Tasks

- [mix cantrip.cast](Mix.Tasks.Cantrip.Cast.md): Cast a single intent to a bare conversation cantrip and print the result.
- [mix cantrip.eval](Mix.Tasks.Cantrip.Eval.md): Run a directory or file of Familiar eval scenarios.
- [mix cantrip.familiar](Mix.Tasks.Cantrip.Familiar.md): Run the Familiar in REPL mode (interactive), single-shot mode, or ACP server mode.

