Metadata-Version: 2.3
Name: actor-ai
Version: 0.1.2
Summary: Multi-provider AI agents built on pykka.
Author: Olivier Steck
Author-email: Olivier Steck <osteck@gmail.com>
Requires-Dist: pykka>=4.0
Requires-Dist: anthropic>=0.40
Requires-Dist: openai>=1.0
Requires-Dist: litellm>=1.0
Requires-Dist: keyring>=25.0
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/oliben67/actor-ai
Project-URL: Repository, https://github.com/oliben67/actor-ai
Project-URL: Documentation, https://github.com/oliben67/actor-ai/blob/master/MANUAL.md
Project-URL: Bug Tracker, https://github.com/oliben67/actor-ai/issues
Description-Content-Type: text/markdown

# actor-ai

**Multi-provider AI agents built on [pykka](https://github.com/jodal/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

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

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

## Quick start

```python
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:

```python
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/`](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:

```bash
uv run python examples/01_hello_world.py
```

## User Manual

See [MANUAL.md](https://github.com/oliben67/actor-ai/blob/master/MANUAL.md) for the complete reference.

## License

MIT
