actor-ai 0.1.2

Multi-provider AI agents built on pykka.

actor-ai

Multi-provider AI agents built on pykka.

actor-ai extends pykka's actor framework so each actor can process natural-language instructions, call tools, maintain conversation sessions, remember facts, track token spend, and monitor traffic — all with a clean, provider-agnostic API.

Installation

pip install actor-ai          # or: uv add actor-ai

Requires Python ≥ 3.14 and one (or more) provider API keys.

Quick start

from actor_ai import AIActor, Claude

class Assistant(AIActor):
    system_prompt = "You are a helpful assistant."
    provider = Claude()          # requires ANTHROPIC_API_KEY

ref = Assistant.start()
reply = ref.proxy().instruct("What is the capital of France?").get()
print(reply)   # → "The capital of France is Paris."
ref.stop()

Providers

Class	Backend	Environment variable
Claude	Anthropic	ANTHROPIC_API_KEY
GPT	OpenAI	OPENAI_API_KEY
Gemini	Google AI (OpenAI-compat)	GOOGLE_API_KEY
Mistral	Mistral AI	MISTRAL_API_KEY
DeepSeek	DeepSeek	DEEPSEEK_API_KEY
Copilot	GitHub Copilot (OpenAI-compat)	GITHUB_TOKEN
LiteLLM	Any (100+ models)	depends on model

Copilot routes requests through GitHub Copilot's OpenAI-compatible endpoint and supports multiple underlying models from a single token:

from actor_ai import AIActor, Copilot

class Assistant(AIActor):
    system_prompt = "You are a helpful coding assistant."
    provider = Copilot()                    # gpt-4o (default)
    provider = Copilot("claude-sonnet-4-5") # Claude via Copilot
    provider = Copilot("gemini-2.0-flash")  # Gemini via Copilot

# See all valid model strings at runtime
print(Copilot.MODELS)

Valid models: gpt-4o, gpt-4o-mini, o1, o1-mini, o3-mini, claude-sonnet-4-5, gemini-2.0-flash. Passing any other string raises ValueError immediately at construction time.

The token is resolved in order: api_key argument → GITHUB_TOKEN env var → gh auth token CLI (no env var needed when the GitHub CLI is authenticated).

Key features

• Multi-turn sessions — rolling conversation history, configurable window (max_history)
• Long-term memory — remember(key, value) / forget(key) facts injected into every system prompt
• Tool calling — decorate methods with @tool to expose them to the LLM
• Chorus — orchestrate groups of agents (broadcast, pipeline)
• Accounting — track token usage and cost per actor, model, and session (Ledger, Rates)
• Monitoring — forward per-call metadata to LiteLLM callbacks (Langfuse, Helicone, custom)

Examples

The examples/ directory contains ten self-contained, runnable scripts.
Each example uses a fake scripted provider so no API key is required to run them.

examples/
  01_hello_world.py    — One-turn interaction
  02_session.py        — Session history, max_history, clear_session
  03_memory.py         — remember() / forget()
  04_tools.py          — @tool decorator and tool calling
  05_providers.py      — All six provider configurations
  06_chorus.py         — Chorus: instruct, broadcast, pipeline
  07_accounting.py     — Ledger and Rates
  08_monitoring.py     — LiteLLM monitoring
  09_messages.py       — Instruct / Remember / Forget message objects
  10_advanced.py       — Full pipeline combining all features

Run any example:

uv run python examples/01_hello_world.py

User Manual

See MANUAL.md for the complete reference.

License

MIT