ZeoCore

ZeoCore is a Python framework for writing capabilities: small, typed, named units of work that anything can call.

You write a function once — giving it an identity, a typed request and response, a declaration of its side effects, and a structured result — and that same function can then be run by a script, served over HTTP, exposed to an MCP-native coding agent like Claude Code or Cursor, or handed to an LLM as a callable tool. You don't rewrite it for each destination.

New here? Start with the Quickstart. It takes you from an empty folder to a running capability in about ten minutes, and assumes no prior knowledge of ZeoCore.

Who this is for

• Students and newcomers learning how to structure real Python tools — typed inputs, explicit error handling, no hidden global state.
• Developers building automation, content pipelines, or integrations who don't want to re-solve configuration, filesystem, and error handling in every project.
• Teams in the Zero Employee ecosystem who need one authoring surface that runners, HTTP services, and agents can all consume.

You should be comfortable writing Python functions and classes. You do not need prior experience with Pydantic, MCP, or agent frameworks.

Requirements

Python 3.14 or newer. That's the only hard requirement. (The floor moved to >=3.14 in 0.6.0, matching sovereign-agent; if you're pinned to an older interpreter, stay on 0.5.0, which requires >=3.13.)

Not sure what you have? Run python3 --version on macOS/Linux or py --version on Windows. The Quickstart walks through installing 3.14 if you need it.

Install

uv pip install zeocore
# or, without uv
pip install zeocore

The package is zeocore; the module you import is zeo_core.

Your first capability

import logging
from tempfile import TemporaryDirectory

from pydantic import BaseModel

from zeo_core.contracts import CapabilityExample, CapabilityResult, EffectKind
from zeo_core.core.fs import get_service as get_fs_service
from zeo_core.tools import ToolContext, bound_capability_of, capability, invoke_sync


class GreetRequest(BaseModel):
    name: str


class GreetResponse(BaseModel):
    message: str


@capability(
    id="demo.greet@1.0.0",
    description="Greet a person by name.",
    effects={EffectKind.READ},
    examples=(
        CapabilityExample(
            request={"name": "World"},
            response={"message": "Hello, World!"},
        ),
    ),
)
def greet(request: GreetRequest, ctx: ToolContext) -> CapabilityResult[GreetResponse]:
    ctx.require_logger().info("greeting %s", request.name)
    return CapabilityResult.ok(data=GreetResponse(message=f"Hello, {request.name}!"))


with TemporaryDirectory() as tmp:
    ctx = ToolContext(
        run_id="demo-run-001",
        tool_name="greet",
        tool_version="1.0.0",
        logger=logging.getLogger("greet"),
        fs=get_fs_service(),
        work_dir=tmp,
        output_dir=tmp,
    )
    result = invoke_sync(bound_capability_of(greet), GreetRequest(name="World"), ctx)
    print(result.status.value, "|", result.data.message)

Expected output:

success | Hello, World!

Line-by-line explanation of that script lives in QUICKSTART.md.

The mental model

Four ideas carry the whole framework.

1. A capability is identified, not just named. Identity is namespace.name@semver (demo.greet@1.0.0), so versions can coexist and callers can pin one.

2. The request and response are Pydantic models. JSON Schema is generated from those models, which is how HTTP, MCP, and LLM adapters can call your capability without you hand-writing schema for each.

3. Everything from the outside world arrives via ToolContext. Logger, filesystem, config, and any services the caller wired in — your capability asks the context instead of reaching for ambient global state. Absence of a declared service fails closed.

4. Expected failures are returned, not raised. A CapabilityResult is success, skip, or error, always structured. Exceptions are for what the caller didn't expect; a CapabilityResult is for what the tool expects and needs to report cleanly — validation failed, a downstream API errored, an optional integration wasn't configured. Callers get one shape to check (result.status, plus fine-grained result.outcome) instead of a try/except matrix, so a runner orchestrating many tools can log, retry, or persist every result the same way. For genuinely exceptional cases, ZeoCore's typed ZeoError hierarchy gives you catchable types instead of string parsing — see examples/error_handling.py.

Class-based tools are still supported: subclass BaseZeoTool, implement run(request, ctx) -> CapabilityResult, and adapt with tool_to_capability. See examples/minimal_tool.py and examples/tool_to_capability.py.

mypy checks all of it end to end.

Learn ZeoCore

Examples

Every example under examples/ is a real, runnable script — none are illustrative fragments. Run any of them with uv run examples/<name>.py.

• capability_authoring.py — canonical @capability authoring, registry, and invoke_sync.
• minimal_tool.py — the smallest class tool: no mixins, no services, just run().
• capability_guards.py — a RequestGuard rejecting a request before the handler runs.
• error_handling.py — the ZeoError family.
• config_usage.py — load_config()'s three real behaviors.

The docs hub indexes all fifteen, grouped by topic.

Examples that need a credential (NOTION_TOKEN, GITHUB_TOKEN, an LLM API key, …) read it from the process environment. Copy .env.example to .env, fill in real values, and load it however your shell or tooling prefers (e.g. uv run --env-file .env ...) — see GET-STARTED.md's "Secrets and .env" section.

Optional integrations

Integrations ship as extras, so you install only what you use:

mcp and mcp-dev are real, separate extras — zeocore[all] does not pull in the MCP adapter. Install it explicitly (e.g. zeocore[all,mcp]). The dev and lint extras are for contributors; see CONTRIBUTING.md.

What's in the package

GET-STARTED.md walks through these module by module.

Quality bar

• mypy --strict, clean across the whole source tree.
• The full test suite runs on every change (a handful are environment-gated and skip/run depending on credentials or OS behavior), with 90.00%+ coverage enforced as a two-decimal hard CI floor (--cov-fail-under=90) — a pull request that drops coverage fails the gate.
• CI runs the full suite on Python 3.14 (the minimum supported interpreter) on every push.
• Production code is not allowed to detect that it's under test (a dedicated CI check fails the build if it finds "pytest" in sys.modules or similar).

Project status

ZeoCore 0.9.0 is a beta library: the API is typed and tested, and this release is the canonical capability-authoring surface for the Zero Employee ecosystem. The surface may still shift before 1.0. Issues, questions, and API feedback are welcome.

Contributing

New contributors start at CONTRIBUTING.md, which covers dev environment setup (make setup), the verification gate (make verify), and how to submit a change. This project follows the Contributor Covenant. Security reports go through SECURITY.md.

Project links

PyPI · Source · Issues · Quickstart · Docs · Manual · Changelog · Contributing · Security

License

MIT — see LICENSE. SPDX: MIT.