zeno-framework 1.0.0rc1

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 (Claude Agent SDK backend)
uv add zeno-framework

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

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

Python 3.12+ required.

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.
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, …).
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 — composable Agent instances with the Task tool for delegation.
• 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.