Eai.Card (eai v1.0.0)

Copy Markdown

Character Card V2 loader and registry.

Cards live in config/chara_cards/ as JSON files. Each card bundles:

  • system_prompt (role-level identity)
  • model, tools, pre_context (via extensions.eai)
  • Character Card V2 spec fields for SillyTavern compatibility

Usage

iex> Eai.Card.names()           # list available card atoms
iex> Eai.Card.list()            # print name → description table
iex> Eai.Card.get(:coder)       # fetch one card
iex> Eai.Chat.talk(chara_card: :frontend_dev, content: "...")

Summary

Functions

all()

Get all registered character cards from config/chara_cards/.

get(name)

Look up card by :name atom.

get!(name)

Look up card by :name atom. Raises if not found.

list()

Print formatted table of available character cards and descriptions.

names()

Get list of all registered card names (atoms).

reload()

Force reload character card registry from disk.

to_opts(card)

Convert card to options for Chat.talk/1 or LLM.Direct.run/3.

Functions

all()

@spec all() :: [keyword()]

Get all registered character cards from config/chara_cards/.

Cards are loaded from :persistent_term cache (set by reload/0).

Returns

List of card keyword lists with keys: `:name`, `:description`, `:model`, `:system_prompt`, `:tools`, `:pre_context`

get(name)

@spec get(atom()) :: keyword() | nil

Look up card by :name atom.

Returns nil if not found.

Options

  • name (atom) — Card name.

Example

iex> Eai.Card.get(:backend_engineer)
[name: :backend_engineer, description: "...", model: :claude_opus, system_prompt: "...", ...]

get!(name)

@spec get!(atom()) :: keyword()

Look up card by :name atom. Raises if not found.

Options

  • name (atom) — Card name.

Raises

ArgumentError if card not found.

list()

@spec list() :: :ok

Print formatted table of available character cards and descriptions.

Example

iex> Eai.Card.list()

Available chara cards:

  :backend_engineer      Scalability-focused, error handling specialist
  :frontend_dev          UI/UX focused, accessibility aware
  :research_analyst      Structured reasoning, hypothesis-driven

names()

@spec names() :: [atom()]

Get list of all registered card names (atoms).

Example

iex> Eai.Card.names()
[:backend_engineer, :frontend_dev, :research_analyst]

reload()

@spec reload() :: [keyword()]

Force reload character card registry from disk.

Useful after editing a .json file in config/chara_cards/.

Returns

List of all reloaded card entries.

to_opts(card)

@spec to_opts(keyword()) :: keyword()

Convert card to options for Chat.talk/1 or LLM.Direct.run/3.

Returns keyword list extracting card fields:

  • :model — if card specifies a model override
  • :card_system_prompt — role-level system prompt
  • :card_tools — allowlist of tool names
  • :card_pre_context — pre-loaded context messages (for prefix caching)

Options

  • card — Card keyword list from Card.get/1 or Card.all/0.

Example

iex> card = Eai.Card.get!(:backend_engineer)
iex> Eai.Card.to_opts(card)
[model: :claude_opus, card_system_prompt: "You are a backend...", card_tools: ["execute_script", "call_subagent"]]