Cantrip.Familiar (Cantrip v1.3.3)

Copy Markdown View Source

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.

Constructs a spec-conformant familiar — a persistent entity that orchestrates other cantrips through code medium.

The familiar observes a codebase through read-only gates, reasons in a code medium, and delegates action to child cantrips that it constructs at runtime — choosing their LLM, medium, gates, and wards based on what the task requires.

Gates:

  • Navigation: list_dir, read_file, search (read-only filesystem)
  • Verification: mix (allowlisted Mix tasks under the workspace root)
  • Orchestration: the public Cantrip package API (Cantrip.new, Cantrip.cast, Cantrip.cast_batch)
  • Control: done (terminate with answer)

The loom is persisted to JSONL. Combined with folding, this gives the familiar long-term memory bounded only by storage.

Summary

Functions

default_system_prompt()

Returns the default system prompt for the Familiar.

new(opts)

Build a familiar cantrip with code medium and orchestration gates.

Functions

default_system_prompt()

Returns the default system prompt for the Familiar.

new(opts)

@spec new(keyword()) :: {:ok, Cantrip.t()} | {:error, String.t()}

Build a familiar cantrip with code medium and orchestration gates.

Options

  • :llm — required, the LLM tuple {module, state}
  • :child_llm — optional, default LLM for child cantrips
  • :max_turns — maximum turns before truncation (default: 20)
  • :loom_path — path for JSONL loom persistence (optional)
  • :root — sandbox root for filesystem gates (optional)
  • :evolve — include the compile_and_load gate and hot-load ward (default: false)
  • :run_tests — include test in the Familiar's default Mix task allowlist (default: false)
  • :allow_mix_tasks — override the Familiar's Mix task allowlist (default: ["compile", "format"], plus "test" when :run_tests is true)
  • :system_prompt — override the default system prompt (optional)
  • :sandbox — :unrestricted (default) runs Familiar code in the host BEAM for trusted operator-local work, so native Elixir affordances such as binding/0 and Code.fetch_docs/1 match the Familiar prompt. :port runs code through Dune in a child BEAM process and resolves gates / child cantrip API calls through the parent runtime. :dune uses the in-process Dune evaluator. :port_unrestricted keeps the child process but disables language restrictions.
  • :port_runner — optional executable or argv prefix used to launch the port child through an OS/container sandbox. When supplied without an explicit :sandbox, the Familiar selects :port so the runner is used.