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.

What you can build with it

Your own tools, written once and used from a script, an HTTP service, an MCP server or an LLM tool call (Quickstart).
Integrations with real services — GitHub, Google Workspace, Notion, Supabase, Bluesky, YouTube, HubSpot, Kit, language models and more — each with a setup guide for credentials and test accounts (integration guides).
A briefing with live cards — flight, weather, arrival timeline and a daily currency watchlist — from keyless public sources, rendered as self-contained HTML and driven by an OpenAI managed agent (briefing cards, Agents API).
The zeocore command, a JSON-lines command line over the same contracts for callers that do not import Python (reference).

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 who want one authoring surface that scripts, 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.12 or newer. That is the only hard requirement, and it is the interpreter Google Colab provides, so ZeoCore runs there without a custom Python.

Not sure what you have? Run python3 --version on macOS/Linux or py --version on Windows. The Quickstart walks through installing a current Python 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.

ZeoCore never reads a provider key for you and never stores one. Anything that needs a credential reads it from your process environment (for example OPENAI_API_KEY), and the example scripts that need one say so at the top. Copy .env.example to .env for local use; .env is git-ignored.

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

Start here	What it gives you
QUICKSTART.md	Install Python 3.12, make a venv, write and run your first capability. No prior knowledge assumed.
docs/README.md	The learning hub: tutorials, a guided path through the examples, and reference material.
docs/tutorials/capability-authoring.md	The canonical authoring tutorial — registry, guards, manifests, adapter binding.
GET-STARTED.md	The full manual: configuration, paths, filesystem, plugins, every integration, adapters, troubleshooting.
docs/reference/api.md	The public API surface, symbol by symbol, and which import paths are supported.
llms.txt	A condensed import map for coding agents.

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 the runnable examples, 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

Optional SDKs ship as extras. Install only what you need:

Extra	What it adds
`zeocore[github]`	GitHub API integration
`zeocore[drive]`	Google Drive
`zeocore[gmail]`	Gmail
`zeocore[calendar]`	Google Calendar (read + write)
`zeocore[google]`	Drive + Gmail + Docs auth plumbing together
`zeocore[youtube]`	YouTube publishing: resumable transfer, schedule, thumbnail, captions, playlists
`zeocore[bluesky]`	Bluesky posting via an app password — no OAuth, no developer app
`zeocore[notion]`	Notion (read + write)
`zeocore[supabase]`	Supabase Database, Auth, Storage, Edge Functions, and async Realtime
`zeocore[pandoc]`	Document conversion via Pandoc
`zeocore[llms]`	OpenAI / Anthropic / tiktoken clients — chat, tool-calling, prompt caching
`zeocore[jupytext]`	Script ↔ Jupyter notebook conversion
`zeocore[notebook]`	Fresh-kernel notebook execution with bounded output
`zeocore[http]`	FastAPI-based HTTP adapter for exposing tools over REST
`zeocore[mcp]`	MCP adapter for exposing tools to Claude Code, Cursor, and other MCP-native agents
`zeocore[runtime-host]`	Supervised capability host and canonical wire validation
`zeocore[all]`	The integration extras; excludes `http`, `mcp`, `runtime-host`, `dev` and `lint`

HubSpot, Kit and the briefing cards are in the base package; their live operations still need your own account or provider terms. The OpenAI managed agent wrapper needs the openai package (3.29 or newer), which you install yourself. mcp is a separate extra: zeocore[all] does not include it (use zeocore[all,mcp]). The dev and lint extras are for contributors; see CONTRIBUTING.md.

What's in the package

Module	What it's for
`zeo_core.tools`	Authoring — `@capability`, `CapabilityRegistry`, `invoke_sync` / `invoke_async`, `BaseZeoTool`, `ToolContext`, `tool_to_capability`, optional mixins.
`zeo_core.contracts`	Data contracts — `CapabilityId`, `CapabilityDefinition`, `CapabilityManifest`, `CapabilityResult`, `CapabilityOutcome`, guards.
`zeo_core.contracts.ui`	Card and widget contracts: `DataRef`, `WidgetUpsert`, `WidgetBoard`.
`zeo_core.execution`	Bounded execution — one total deadline, explicit retries and fallback, cancellation, sanitized attempt records.
`zeo_core.adapters`	HTTP, MCP and LLM function adapters, the Runtime capability host, and `widget_html` (cards to self-contained HTML).
`zeo_core.integrations`	Adapters for GitHub, Google Workspace, Supabase, LLM providers, Notion, HubSpot, Kit, Gemini images, Pandoc, jupytext, notebooks, ffmpeg, the OpenAI managed Agents API (`agents`) and keyless public briefing sources (`briefing_sources`).
`zeo_core.core`	Filesystem operations, path resolution, a typed error hierarchy, MIME detection, serialization, logging.
`zeo_core.config`	YAML/env-var configuration loading and per-tool config models.
`zeo_core.modules`	Plugin discovery and explicit-loading registry.
`zeo_core.prompt`	Prompt template selection and enhancement utilities.

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

Quality bar

mypy --strict, clean across the whole source tree.
The full test suite runs after every merge to main and nightly, on Python 3.12 (the minimum supported interpreter) and 3.14 (the newest); pull requests run a fast smoke job first. Coverage is held to a 90% hard floor.
Production code is not allowed to detect that it is under test (a dedicated CI check fails the build if it finds "pytest" in sys.modules or similar).

Project status

ZeoCore is a beta library: the API is typed and tested, but the surface may still shift before 1.0. Every merge to main is a release — see the GitHub releases for what changed in each version. Issues, questions and API feedback are welcome.

Contributing

New contributors start at CONTRIBUTING.md. 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.

Metadata

Release files for zeocore 0.36.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zeocore 0.36.2
File	Size	Uploaded	Provenance
zeocore-0.36.2.tar.gz	2.4 MB	Oct 22, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for zeocore 0.36.2
File	Interpreter	ABI	Platform	Reset
zeocore-0.36.2-py3-none-any.whl 1.0 MB Oct 22, 2026 With provenance	Python 3	none	any	Details

Total release size: 3.4 MB

Release files / zeocore-0.36.2.tar.gz

Download URL	zeocore-0.36.2.tar.gz
Size	2.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`7a0d1fc38bfcab4daa23132e5aace44bb03b25faaabd9b4ad5b893a660a56193`
BLAKE2b-256 checksum How to use checksums	`b6e24158e27bb8debe328fbeaa0b11cdd85419daa809252ac75d2aacb7a5900d`
Upload date	Oct 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/zeroemployeeorg/zeocore
Publishing commit: github.com/zeroemployeeorg/zeocore/tree/bf32581eb2a695ffda73c7fc891aa96495522bda

Workflow

Publishing configuration: github.com/zeroemployeeorg/zeocore/blob/bf32581eb2a695ffda73c7fc891aa96495522bda/.github/workflows/publish.yml
Publishing logs: github.com/zeroemployeeorg/zeocore/actions/runs/39733500568/attempts/1

Artifact

Subject: zeocore-0.36.2.tar.gz
SHA-256 checksum: 7a0d1fc38bfcab4daa23132e5aace44bb03b25faaabd9b4ad5b893a660a56193 Verifying attestations

Release files / zeocore-0.36.2-py3-none-any.whl

Download URL	zeocore-0.36.2-py3-none-any.whl
Size	1.0 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`f831fd517bdad8395b7f376cd2415639b1b8581d844bd973c413b308bf5dfd7e`
BLAKE2b-256 checksum How to use checksums	`e8cf06d285e5baec20a3b46ebe505945a3d75ed2bf9e1bfc13ce137c26ccdcf3`
Upload date	Oct 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/zeroemployeeorg/zeocore
Publishing commit: github.com/zeroemployeeorg/zeocore/tree/bf32581eb2a695ffda73c7fc891aa96495522bda

Workflow

Publishing configuration: github.com/zeroemployeeorg/zeocore/blob/bf32581eb2a695ffda73c7fc891aa96495522bda/.github/workflows/publish.yml
Publishing logs: github.com/zeroemployeeorg/zeocore/actions/runs/39733500568/attempts/1

Artifact

Subject: zeocore-0.36.2-py3-none-any.whl
SHA-256 checksum: f831fd517bdad8395b7f376cd2415639b1b8581d844bd973c413b308bf5dfd7e Verifying attestations

Security for zeocore 0.36.2

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for zeocore-0.36.2.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/zeroemployeeorg/zeocore
Publishing commit: github.com/zeroemployeeorg/zeocore/tree/bf32581eb2a695ffda73c7fc891aa96495522bda

Workflow

Publishing configuration: github.com/zeroemployeeorg/zeocore/blob/bf32581eb2a695ffda73c7fc891aa96495522bda/.github/workflows/publish.yml
Publishing logs: github.com/zeroemployeeorg/zeocore/actions/runs/39733500568/attempts/1

Artifact

Subject: zeocore-0.36.2.tar.gz
SHA-256 checksum: 7a0d1fc38bfcab4daa23132e5aace44bb03b25faaabd9b4ad5b893a660a56193 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.