zymi-core

<p align="center"> <img src="https://raw.githubusercontent.com/metravod/zymi-core/main/assets/zymi-badge.png" alt="zymi" width="220" /> </p> <h1 align="center">zymi-core</h1> <p align="center"><em>The auditable MCP backend for agents — tools as declarative YAML pipelines: event-sourced, replayable, approval-gated.</em></p> <p align="center">_{Pronounced <em>zoomi</em> — like dog zoomies.}</p> <p align="center"> <a href="https://pypi.org/project/zymi-core/"><img src="https://img.shields.io/pypi/v/zymi-core.svg?logo=pypi&logoColor=white" alt="PyPI" /></a> <a href="https://pypi.org/project/zymi-core/"><img src="https://img.shields.io/pypi/pyversions/zymi-core.svg?logo=python&logoColor=white" alt="Python versions" /></a> <a href="https://github.com/metravod/zymi-core/actions/workflows/ci.yml"><img src="https://github.com/metravod/zymi-core/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a> <a href="llms.txt"><img src="https://img.shields.io/badge/llms.txt-%E2%9C%93-8A2BE2" alt="llms.txt" /></a> </p>

---

Why zymi-core?

Agent frameworks compete for the front of the stack — the loop, the planner, the IDE. zymi owns the back: the tools your agent calls.

zymi mcp serve exposes declarative YAML pipelines as MCP tools to any host — Claude Code, Claude Desktop, Cursor, or any framework with an MCP adapter (LangGraph, CrewAI, OpenAI Agents SDK). Unlike a script behind an endpoint, a zymi tool is:

• Declarative, like dbt. Agents, pipelines, tools, connectors, approvals — all YAML. The engine validates and runs them as a DAG.
• Event-sourced. Every state change is an immutable, hash-chained event. Runs are replayable, resumable, and auditable without extra logging.
• Boundary-safe — interactively. Steps emit intentions (run shell, write file, call HTTP) that pass through policy + contracts + optional human approval before execution. Over MCP the approval renders as an approve/deny form right in the calling agent's UI; the risky thing doesn't happen until someone says yes.
• Self-debuggable. Serve with --expose-observability and the agent can introspect its own runs — list them, pull the event trace, read any step's exact I/O — and explain a failure without you opening a log file.

zymi is deliberately not an autonomous coding agent, an IDE plugin, or a chat UI — it's the governed tool layer underneath those. It also runs standalone: bring a Telegram agent online in two minutes, no MCP involved. Either way, a year later you can still answer exactly what this agent did on any past run.

📚 AI-assistant friendly out of the box. Every zymi init scaffold drops an AGENTS.md into the user's project — vocabulary, file map, task→file routing. Claude Code / Cursor / Aider read it automatically; the YAML they help you write gets noticeably more correct. For agents that build zymi projects (rather than work inside one), install zymi-skill into your assistant — opinionated Agent Skill with activation rules + progressive disclosure references, so the assistant produces zymi-native YAML instead of generic agent advice.

---

Run a Telegram agent in two minutes

The canonical standalone demo (no MCP host needed) — a real chat bot, wired declaratively.

uv tool install zymi-core    # one-time; puts `zymi` on PATH globally

mkdir telegram-agent && cd telegram-agent
zymi init --example telegram

# 1. Create a bot via @BotFather in Telegram; copy the token.
# 2. Fill .env:
cp .env.example .env         # edit TELEGRAM_BOT_TOKEN + OPENAI_API_KEY
# 3. Open project.yml, replace "your_username_here" with your actual
#    Telegram username (no @). Keeps strangers out of the bot.

zymi fetch                   # uv sync — builds ./.venv from pyproject.toml
zymi serve chat              # .env is auto-loaded; pipeline runs in ./.venv

Why uv tool install and zymi fetch? zymi is a global CLI; your project keeps its own pyproject.toml + .venv for any Python deps your @tool files import. zymi fetch wraps uv sync to build that venv, and pipeline-run commands transparently re-exec inside it (ADR-0032). Don't have uv yet? curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or irm https://astral.sh/uv/install.ps1 | iex (Windows).

Message the bot. It replies in seconds. Every inbound message, LLM call, approval decision, and outbound reply is in .zymi/events.db; watch live with zymi observe.

The whole wiring — Telegram I/O, two-step DAG (assistant drafts, reviewer polishes), declarative + Python tools, approval channel — lives in YAML. The scaffold also drops AGENTS.md so an AI coding assistant can extend the project safely. Concrete demo of:

• http_poll connector — long-polls Telegram's getUpdates, no HTTPS / ngrok needed
• http_post output — sends each ResponseReady back to the user
• Telegram approval channel — DMs admins with ✅ / ❌ buttons when the agent calls broadcast (requires_approval: true)
• Python @tool auto-discovery — drop tools/get_weather.py (sync) or tools/translate.py (async) and the agent picks them up

Ask the bot to "announce that we're closing at 5pm" — the agent calls broadcast, you get a DM with approve/deny buttons, nothing goes out until you click. End-to-end audit trail in zymi events.

Full setup in docs/getting-started.md. Connector deep-dive in docs/connectors.md. Approvals in docs/approvals.md.

---

What's in the box

Pipelines — DAGs, agent steps, deterministic tool steps, ask steps

A pipeline is a list of steps with depends_on: edges. Independent steps run in parallel. Each step is an agent step (LLM ReAct loop), a deterministic tool step (ADR-0024) — direct dispatch with templated args, no LLM hop, but the same event envelope — or an ask step (ADR-0042): delegate a reasoning question to whoever called the pipeline instead of configuring a second, separately-billed model. The run parks, asks the caller, and resumes with the answer (a human at the terminal under zymi run; the connected agent under zymi mcp serve).

Mix them freely:

steps:
  - id: fetch                            # deterministic — no LLM
    tool: http_get
    args: { url: "https://api.example.com/${inputs.id}" }

  - id: classify                         # LLM
    agent: classifier
    task: "${steps.fetch.output}"
    depends_on: [fetch]

  - id: sanity                           # ask — the caller answers, no llm: needed
    ask: "Does this classification look right?\n${steps.classify.output}"
    depends_on: [classify]

Conditional branches (ADR-0028) — a step can gate on an upstream output. Skipped branches cascade to descendants and emit StepSkipped events, so routing decisions land in the trace, not in the LLM's head:

- id: router
  agent: concierge
  task: "Pick: ${inputs.q}"   # calls route('short' | 'rag')

- id: rag_lookup
  tool: pinecone_query
  args: { query: "${inputs.q}" }
  depends_on: [router]
  when: "${steps.router.output} == 'rag'"

Schema, examples, gotchas → docs/pipelines.md.

Tools — four kinds, one catalogue

All four kinds emit identical ToolCallRequested / ToolCallCompleted events; the agent doesn't know which catalogue a tool came from.

• Declarative HTTP / shell in tools/<name>.yml — no code.
• Python @tool in tools/<name>.py — sync or async, signature → JSON Schema, auto-discovered.
• MCP servers — one mcp_servers: entry gives N tools, namespaced mcp__<server>__<tool> (ADR-0023).
• Builtins — read_file, write_file, write_memory, execute_shell_command, spawn_sub_agent.

# tools/get_weather.py — auto-discovered at runtime startup.
from zymi import tool

@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"sunny in {city}"

Schema and the four kinds in detail → docs/tools.md.

zymi as an MCP server — pipelines as tools for any agent

The mirror of the MCP client above: zymi mcp serve exposes your pipelines as MCP tools over stdio, so any MCP host (Claude Code, Claude Desktop, Cursor, the OpenAI Agents / LangGraph / OpenHands runtimes via their MCP adapters) can call a zymi pipeline as a single tool — no per-runtime glue (ADR-0033).

This is the priority direction for zymi: own the auditable, event-sourced back of the agent stack rather than competing on the front. A pipeline is a tool whose every step is hash-chained, replayable, and resumable — which is exactly what an agent's tool catalogue is missing.

Exposure is opt-in per pipeline (so internal/cron pipelines never leak into agent tool catalogues):

# pipelines/research.yml
expose:
  mcp:
    name: research            # tool name (defaults to file stem)
    mode: sync | async        # async hints the caller to task-augment (SEP-1686)
    description: "Deep-research a topic and return a brief."

zymi mcp serve                              # serve all expose:-d pipelines over stdio
zymi mcp serve --include 'research_*' --exclude '*_internal'

• Sync — tools/call blocks until the pipeline finishes; works on every MCP client today. Tool input schema is auto-generated from the pipeline's inputs:.
• Async — a client that augments the call with a SEP-1686 task gets a CreateTaskResult immediately and polls tasks/get / tasks/result / tasks/list; tasks/cancel and notifications/cancelled cancel it. The pipeline runs in the background and stays fully observable in the event store.

Human approvals render in the calling agent's UI. A pipeline step that trips an approval sends a server-initiated elicitation/create back through the live tools/call — in Claude Code that's a native approve/deny form. Approve and the pipeline continues; deny and it halts with the decision in the audit trail; a client without elicitation support fail-closes (ApprovalDenied{reason: client_no_elicitation}). Verified live against Claude Code.

The pipeline can borrow the caller's brain. An ask: step (ADR-0042) delegates a reasoning question back to the calling agent instead of configuring a second model. On a task-augmented call the run parks, the task goes input_required carrying { prompt, resume_token }, and the caller reasons in its own loop and calls zymi/reasoning/resume { resume_token, answer } — no sampling, no deprecated primitives, just tools + park/resume. The prompt and answer are recorded, so replay reads the answer back byte-identical. A pure tool + ask pipeline needs no llm: at all. Verified live against zymi mcp serve.

The agent can debug its own runs. zymi mcp serve --expose-observability adds four read-only tools — zymi.runs.list / .get / .events / .step_io (ADR-0034). Ask the agent "why did the last run fail?" and it pulls the event trace and answers with the exact policy verdict and approval decision — introspection other stacks can't expose because the per-step event granularity isn't there. Scoped to the serve session by default; --observability-scope all opens the whole store for single-user dev.

**Current limitations (hone