Metadata-Version: 2.4
Name: zeno-framework
Version: 1.0.2
Summary: Meta-package for the Zeno AI assistant framework.
Project-URL: Homepage, https://github.com/nkootstra/zeno
Project-URL: Repository, https://github.com/nkootstra/zeno
Project-URL: Issues, https://github.com/nkootstra/zeno/issues
Project-URL: Changelog, https://github.com/nkootstra/zeno/blob/main/CHANGELOG.md
Author: Niels Kootstra
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,async,claude,framework,llm,zeno
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: zeno-core
Requires-Dist: zeno-provider-claude
Provides-Extra: all
Requires-Dist: zeno-channel-cli; extra == 'all'
Requires-Dist: zeno-channel-email; extra == 'all'
Requires-Dist: zeno-channel-sendblue; extra == 'all'
Requires-Dist: zeno-chroma; extra == 'all'
Requires-Dist: zeno-memory; extra == 'all'
Requires-Dist: zeno-provider-claude; extra == 'all'
Requires-Dist: zeno-provider-openai; extra == 'all'
Requires-Dist: zeno-qdrant; extra == 'all'
Requires-Dist: zeno-scheduler; extra == 'all'
Requires-Dist: zeno-secrets-1password; extra == 'all'
Requires-Dist: zeno-tools-things; extra == 'all'
Provides-Extra: browser
Requires-Dist: zeno-tools-browser; extra == 'browser'
Provides-Extra: chroma
Requires-Dist: zeno-chroma; extra == 'chroma'
Requires-Dist: zeno-memory; extra == 'chroma'
Provides-Extra: claude
Requires-Dist: zeno-provider-claude; extra == 'claude'
Provides-Extra: cli
Requires-Dist: zeno-channel-cli; extra == 'cli'
Provides-Extra: email
Requires-Dist: zeno-channel-email; extra == 'email'
Provides-Extra: memory
Requires-Dist: zeno-memory; extra == 'memory'
Provides-Extra: openai
Requires-Dist: zeno-provider-openai; extra == 'openai'
Provides-Extra: qdrant
Requires-Dist: zeno-memory; extra == 'qdrant'
Requires-Dist: zeno-qdrant; extra == 'qdrant'
Provides-Extra: scheduler
Requires-Dist: zeno-scheduler; extra == 'scheduler'
Provides-Extra: secrets-1password
Requires-Dist: zeno-secrets-1password; extra == 'secrets-1password'
Provides-Extra: sendblue
Requires-Dist: zeno-channel-sendblue; extra == 'sendblue'
Provides-Extra: things
Requires-Dist: zeno-tools-things; extra == 'things'
Description-Content-Type: text/markdown

# zeno-framework

A modular Python framework for building AI assistants. Bring an LLM, plug
in channels (CLI, email, iMessage), wire memory adapters (SQLite,
Chroma, Qdrant), and ship.

`zeno-framework` is a meta-package — it ships no code of its own and pulls in
the right combination of `zeno-*` packages via extras.

## Install

```bash
# minimal core — ships the Claude provider by default
uv add zeno-framework

# terminal chat with memory
uv add 'zeno-framework[memory,cli]'

# OpenAI-compatible provider on top of the default Claude provider
uv add 'zeno-framework[openai]'

# the full kitchen sink
uv add 'zeno-framework[all]'
```

Python 3.12+ required.

By default, `pip install zeno-framework` installs `zeno-provider-claude`
so `ClaudeSDKProvider` works out of the box. To use OpenAI-compatible
endpoints (OpenAI, OpenRouter, LiteLLM, Azure v1, Ollama, vLLM), add
the `openai` extra. The `claude` extra is also declared for explicit
installs but is redundant with the default.

## Hello world

```python
import asyncio

from zeno.agent import Agent
from zeno.app import ZenoApp
from zeno.channels.cli.channel import CliChannel
from zeno.providers.claude_sdk import ClaudeSDKProvider


async def main() -> None:
    app = ZenoApp(
        agent=Agent(
            name="root",
            instructions="You are a helpful assistant.",
        ),
        channels=[CliChannel()],
        provider=ClaudeSDKProvider(),
    )
    await app.run()


asyncio.run(main())
```

```bash
export ANTHROPIC_API_KEY=sk-ant-...
uv run python hello.py
```

That's a working terminal-chat assistant. Add memory, more channels, or
swap the provider as you grow.

## Extras

| Extra               | Pulls in                                                              | What you get                                                          |
| ------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `memory`            | [`zeno-memory`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-memory) | SQLite session, conversation, and user-memory stores. |
| `chroma`            | `zeno-memory` + [`zeno-chroma`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-chroma) | ChromaDB-backed `KnowledgeStore` for RAG.      |
| `qdrant`            | `zeno-memory` + [`zeno-qdrant`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-qdrant) | Qdrant-backed `KnowledgeStore` for RAG.         |
| `cli`               | [`zeno-channel-cli`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-channel-cli) | Terminal channel (stdin/stdout with streaming).        |
| `email`             | [`zeno-channel-email`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-channel-email) | Email channel (Resend inbound + outbound).           |
| `sendblue`          | [`zeno-channel-sendblue`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-channel-sendblue) | iMessage channel via Sendblue webhooks.       |
| `claude`            | [`zeno-provider-claude`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-provider-claude) | Claude Agent SDK provider (default; redundant extra for explicit installs). |
| `openai`            | [`zeno-provider-openai`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-provider-openai) | OpenAI-compatible provider (OpenAI, OpenRouter, LiteLLM, Azure v1, Ollama, vLLM). |
| `scheduler`         | [`zeno-scheduler`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-scheduler) | Proactive triggers: one-shot, heartbeat, cron.       |
| `browser`           | [`zeno-tools-browser`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-tools-browser) | Playwright-backed browser tools (`browse`, `click`, …). |
| `things`            | [`zeno-tools-things`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-tools-things) | Things 3 / Things Cloud todo tools (`things_list`, `things_add`, `things_complete`). |
| `secrets-1password` | [`zeno-secrets-1password`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-secrets-1password) | 1Password CLI-backed `SecretsStore` adapter. |
| `all`               | every extra above (except `browser`, which carries Playwright)        | Everything bundled.                                                  |

[`zeno-core`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-core)
is always installed — it provides the `Agent`, `ZenoApp`, `Ctx`, `@tool`,
provider/channel protocols, and the turn worker.

## What's in the framework

- **Agents and sub-agents** — a root `Agent` orchestrates and delegates
  to specialist `SubAgent` instances. Each sub-agent declares its own
  `tools`, `built_in_tools`, and `max_turns`; the Claude provider
  translates them to native dispatch via the SDK's `Task` tool. See the
  "Composing specialists" section in the
  [root README](https://github.com/nkootstra/zeno#composing-specialists).
- **Tools** — `@tool` decorator with auto-injection of `Ctx`, secrets,
  and memory binders.
- **Channels** — pluggable transports (`CliChannel`, `EmailChannel`,
  `SendblueChannel`); contributed via the `zeno.channels` entry-point
  group.
- **Providers** — `ClaudeSDKProvider` (default) and `OpenAIProvider`;
  contributed via the `zeno.providers` entry-point group.
- **Memory** — three-layer model (session, conversation, user memory)
  with SQLite defaults and pluggable vector knowledge stores.
- **Scheduler** — proactive triggers for cron/heartbeat workflows.
- **Secrets** — `SecretsStore` protocol with env-var default and
  optional 1Password adapter.

See the [example chat
app](https://github.com/nkootstra/zeno/tree/main/apps/zeno-example-chat)
for a complete reference implementation in ≤150 lines.

## Links

- Source code & issues: <https://github.com/nkootstra/zeno>
- Changelog: <https://github.com/nkootstra/zeno/blob/main/CHANGELOG.md>
- Security policy: <https://github.com/nkootstra/zeno/blob/main/SECURITY.md>
- Contributing: <https://github.com/nkootstra/zeno/blob/main/CONTRIBUTING.md>

MIT licensed.
