Modules
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.
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.
Run this to expose the Familiar to ACP-aware editors over stdio. The
mix cantrip.familiar --acp task calls into this server.
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.
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.
Script deterministic LLM responses for tests and evals. Use this when you need runtime evidence without provider calls; it tests shape, not behavioral quality.
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.
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.
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.
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.
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.
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.
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.
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.
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
Cast a single intent to a bare conversation cantrip and print the result.
Run a directory or file of Familiar eval scenarios.
Run the Familiar in REPL mode (interactive), single-shot mode, or ACP server mode.