ZeoCore

A typed capability-authoring framework for Python. Declare a capability once — namespaced identity, Pydantic request/response, declared effects, structured result — and invoke it from a runner, an HTTP API, MCP, or an LLM tool list. SPDX: MIT.

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.data.message)  # Hello, World!

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

Every capability takes a typed request, runs against an immutable ToolContext (logger, filesystem, config, and any services the runner wires in), and returns a CapabilityResult — success, skip, or error, always structured. mypy checks it end to end.

Why a typed result instead of "just raise an exception"

Exceptions are for things the caller didn't expect. A CapabilityResult is for things the tool expects and needs to report cleanly: validation failed, a downstream API returned an error, 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, and a runner orchestrating many tools can log, retry, or persist every result the same way.

If a tool does hit something genuinely exceptional, ZeoCore's typed error hierarchy (ZeoError and its subclasses) gives you catchable types instead of parsing a string. See examples/error_handling.py.

Install

Requires Python 3.13 or newer. The floor moved from >=3.10 to >=3.13 in an earlier cycle. If you're pinned to an older Python, stay on a pre-floor-bump release.

pip install zeocore
# or
uv pip install zeocore

Optional integrations ship as extras, so you only install what you use:

dev and lint extras exist too, for contributors — see CONTRIBUTING.md (make setup, then make verify). mcp/mcp-dev are real, separate extras — zeocore[all] does not pull in the MCP adapter; install zeocore[mcp] explicitly (e.g. zeocore[all,mcp]).

More examples

• examples/capability_authoring.py — canonical @capability authoring, registry, and invoke_sync.
• examples/capability_guards.py — RequestGuard rejecting a request before the handler runs.
• examples/tool_to_capability.py — adapt a BaseZeoTool class into a BoundCapability.
• examples/llm_tools_usage.py — project a CapabilityManifest to an OpenAI function tool (or refuse).
• examples/minimal_tool.py — the smallest class tool: no mixins, no services, just run().
• examples/toolkit_usage.py — lifecycle hooks, an optional integration, graceful skip when a service isn't wired.
• examples/error_handling.py — the ZeoError family.
• examples/config_usage.py — load_config()'s three real behaviors.
• examples/http_adapter_usage.py — bind a capability into OperationRegistry and exercise the FastAPI app (zeocore[http]).
• examples/mcp_server_usage.py — expose a tool as an MCP server (zeocore[mcp]).
• examples/explicit_plugin_loading_example.py — discover and load plugins without import-time side effects.
• examples/notion_usage.py — Notion read/write, skipped when NOTION_TOKEN isn't set.
• examples/calendar_usage.py — Google Calendar read/write, skipped when OAuth isn't configured.
• examples/jupytext_usage.py — script ↔ notebook round-trip.
• examples/ffmpeg_usage.py — probe, transcode, and thumbnail a synthetic test video.

Every example is runnable as-is: python examples/<name>.py. None of them are illustrative fragments.

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/tooling prefers (e.g. uv run --env-file .env ...) — see GET-STARTED.md's "Secrets and .env" section.

What's in the package

See GET-STARTED.md for a module-by-module walkthrough, including the Capabilities section. docs/ indexes tutorials (MCP, Notion, Calendar, capability authoring) separately from maintainer reports. llms.txt is a condensed summary for coding agents.

Quality bar

• mypy --strict, clean across the whole source tree.
• 2494 tests, 90%+ coverage, enforced as a hard CI floor (--cov-fail-under=90) — a pull request that drops coverage fails the gate.
• CI runs the full suite on Python 3.13 (zeocore's 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.5.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

See CONTRIBUTING.md for dev environment setup, the verification gate (make verify), and how to submit a change. This project follows the Contributor Covenant.

Project links

PyPI · Source · Issues · Changelog · Get started · Contributing · Security

License

MIT — see LICENSE.