zeno-framework 1.0.2

Meta-package for the Zeno AI assistant framework.

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

# 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

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())

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

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.
• 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 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.