# zymi-core

> Auditable MCP backend for agents: `zymi mcp serve` exposes declarative YAML pipelines as MCP tools with event-sourced audit trail, deterministic replay, interactive human approval gates (MCP elicitation), and self-introspection tools (`zymi.runs.*`). Also a standalone YAML-first agent engine with pluggable connectors. Installed as a global CLI with `uv tool install zymi-core` (or `pip install zymi-core` to embed the Python API in a venv); also a Rust crate.

## Quick start

- [README](README.md): pitch, 60-second start, feature tour
- [Getting started](docs/getting-started.md): `uv tool install` → `zymi init` → `zymi fetch` → first run, end-to-end

## Reference

- [Project YAML](docs/project-yaml.md): `project.yml` schema (llm, defaults, policy, contracts, variables, store, connectors, outputs, approvals, mcp_servers, default_approval_channel)
- [Agents](docs/agents.md): `agents/<name>.yml` schema and the ReAct loop
- [Pipelines](docs/pipelines.md): `pipelines/<name>.yml` schema, agent steps and deterministic tool steps (ADR-0024), DAG semantics, conditional edges via `when:` (ADR-0028), `${inputs.*}` / `${steps.<id>.output}` interpolation
- [Tools](docs/tools.md): four tool kinds — declarative HTTP/shell, Python `@tool`, MCP, builtin
- [Connectors](docs/connectors.md): inbound (`http_inbound`, `http_poll`, `cron`, `file_read`, `stdin`) and outbound (`http_post`, `file_append`, `stdout`)
- [Approvals](docs/approvals.md): event-sourced human-in-the-loop, channels (`terminal`, `http`, `telegram`, auto `mcp_elicitation` under `zymi mcp serve`), restart-safe replay (ADR-0022)
- MCP server: `zymi mcp serve` — pipelines as MCP tools (opt-in `expose.mcp:`), sync + SEP-1686 async tasks, approval gates as elicitation forms in the host, `--expose-observability` for `zymi.runs.list/get/events/step_io` (ADR-0033, ADR-0034); see README §"zymi as an MCP server"
- [Store backends](docs/store-backends.md): SQLite (default) vs Postgres (multi-process `zymi serve` against a shared store)
- [Events and replay](docs/events-and-replay.md): event-sourcing model, stream and hash-chain semantics, `zymi events` / `runs` / `verify` / `observe`, fork-resume
- [CLI reference](docs/cli.md): every `zymi` subcommand with flags and examples
- [Python API](docs/python-api.md): `Runtime`, `EventStore`, `EventBus`, `ToolRegistry`, `@tool` decorator, `_cli.main`

## Architecture decisions

- [ADR index](adr/): one file per decision; canonical context for design tradeoffs

## For AI assistants building with zymi

- [zymi-skill](https://github.com/metravod/zymi-skill): opinionated Agent Skill (SKILL.md + references/) for Claude Code / Codex / any agent-skills-compatible harness. Activates on mentions of `zymi`, edits to `project.yml` / `pipelines/*.yml` / `tools/*.py`, or working directories containing `.zymi/`. Drop it in `~/.claude/skills/` (or the equivalent for your tool) and the assistant produces zymi-native YAML instead of translating from generic agent advice.

## Optional

- [CONTRIBUTING](CONTRIBUTING.md): contributor flow, build matrix, release process