arcana-core

The Python library at the heart of Arcana OS. Assign a tarot card to an agent: get a soul.

pip install arcana-core
# or inside the monorepo:
uv sync --all-packages --all-extras

Quick start

Agents run through a ModelGateway. The gateway owns connections, routing, retries, and cost metering; the agent just names the model it wants.

from arcana import Agent, Card
from arcana.models import ConnectionStore, ModelGateway

async with ModelGateway(ConnectionStore()) as gw:
    agent = Agent(
        name="researcher",
        card=Card.HERMIT,
        gateway=gw,
        model="ollama/hermes-3",
    )

    result = await agent.run("Summarise recent advances in RAG.")
    print(result)

    # Streaming
    async for chunk in agent.stream("What is a vector index?"):
        print(chunk, end="", flush=True)

How it works

Every agent is configured by a tarot card. The card encodes an archetype: personality and default temperature. The CardEngine blends one primary card with optional modifier cards into an AgentConfig, which the Agent wires together with the gateway.

Card enum
  → CardRegistry.get()   → TarotCard  (archetype, traits, prompt ingredients)
  → CardEngine.resolve() → AgentConfig (system_prompt, temperature)
  → Agent.__init__()      ← wires gateway + model + AgentConfig together
  → Agent.run() / Agent.stream()

Blending: primary card = 70%, modifier cards = 30% split equally. Temperature is linearly blended. CardEngine.check_compatibility() reports how well a primary and its modifiers fit together.

agent = Agent(
    name="creative-researcher",
    card=Card.HERMIT,            # 70 % — deep, methodical
    modifier_cards=[Card.FOOL],  # 30 % — curious, action-first
    gateway=gw,
    model="ollama/hermes-3",
)

Each run records a Session (messages + token totals). Sessions are stateless in this release — multi-turn continuity within a session is supported; cross-session memory is not yet wired (see the roadmap).

The 22 Major Arcana

The World (XXI) is defined but reserved — it cannot be assigned to an agent yet.

Module map

Types convention

All Pydantic models are re-exported from arcana.types. Always import from there:

from arcana.types import Card, AgentConfig  # correct
from arcana.types.card import Card           # avoid

Adding a new card

1. Create arcana/cards/definitions/<name>.py following fool.py — export a single TarotCard instance.
2. Import it in arcana/cards/definitions/__init__.py and add it to all_cards() in canonical order.
3. Add the Card enum value to arcana/types/card.py if not already present.

Development

# Lint
uv run ruff check .

# Type check
uv run pyright packages/arcana-core/arcana

# Tests (no LLM calls)
uv run pytest packages/arcana-core/tests/ -v -m "not llm_eval"

Roadmap

This release ships the Phase 1a MVP: card-configured, stateless agents on the model gateway. The federated memory layer now lives in arcana-core (tiered backends, folder connectors, and a knowledge-graph edge layer — see the module map), usable directly as a library. Wiring it into the agent run path — plus a tool/MCP gateway and The World meta-agent — lands in Phase 1b as additive work, not a rewrite.