# ZeoCore

> A typed capability-authoring framework for Python. Write a tool once —
> validated input, one method of real work, a structured result — and run
> it inside any runner that respects the contract. Every tool takes a
> typed Pydantic request, runs against an immutable `ToolContext`, and
> returns a `CapabilityResult` (success/skip/error, never a bare
> exception or an untyped dict). PyPI distribution name: `zeocore`;
> import name: `zeo_core`.

Start here, in order: read README.md for the 60-second `@capability`
shape, then GET-STARTED.md (especially Capabilities), then
docs/tutorials/capability-authoring.md, then copy the closest-matching
file under examples/ — every one of them is runnable as printed
(`uv run examples/<name>.py`), not an illustrative fragment.

## Core docs

- [README.md](README.md): Quick start, install/extras table, module
  overview, quality bar (mypy --strict, 90%+ coverage, tests on Python
  3.14 — the package's own floor, requires Python >=3.14).
- [GET-STARTED.md](GET-STARTED.md): The full walkthrough — configuration,
  path resolution, filesystem operations, typed error handling, writing a
  capability (`@capability` / `BaseZeoTool`), integrations (Google
  Drive/Gmail/Calendar, GitHub, Notion, Pandoc, jupytext, ffmpeg, LLM
  providers), exposing tools over HTTP or MCP, OpenAI function
  projection, and a troubleshooting section.
- [docs/README.md](docs/README.md): tutorial index vs maintainer reports.
- [docs/tutorials/capability-authoring.md](docs/tutorials/capability-authoring.md):
  define → register → invoke → project OpenAI → bind HTTP/MCP.
- [docs/tutorials/](docs/tutorials/): MCP with Claude Code/Cursor, Notion,
  Google Calendar.
- [CHANGELOG.md](CHANGELOG.md): Version history (Keep a Changelog).
  RELEASE_NOTES.md describes the current 0.10.0 release; CHANGELOG.md is the
  full history.
- [CONTRIBUTING.md](CONTRIBUTING.md): Dev setup, the gate
  (`make verify` / `make verify-full`), code style, canonical import
  paths.
- [SECURITY.md](SECURITY.md): How to report vulnerabilities.

## Examples (all runnable as-is)

- [examples/capability_authoring.py](examples/capability_authoring.py):
  Canonical `@capability` function authoring and `CapabilityRegistry`.
- [examples/capability_guards.py](examples/capability_guards.py):
  `RequestGuard` rejecting a request before the handler runs.
- [examples/tool_to_capability.py](examples/tool_to_capability.py):
  Adapt `BaseZeoTool` → `BoundCapability`.
- [examples/llm_tools_usage.py](examples/llm_tools_usage.py):
  `project_openai_tool` from a `CapabilityManifest` (or typed refusal).
- [examples/minimal_tool.py](examples/minimal_tool.py): The smallest
  possible class tool — no mixins, no services, just `run()`.
- [examples/toolkit_usage.py](examples/toolkit_usage.py): Lifecycle
  hooks, optional integration, graceful skip when a service isn't wired.
- [examples/error_handling.py](examples/error_handling.py): The
  `ZeoError` family and `@wrap_io_errors`.
- [examples/config_usage.py](examples/config_usage.py): `load_config()`'s
  three real behaviors.
- [examples/http_adapter_usage.py](examples/http_adapter_usage.py): Bind
  a capability into `OperationRegistry` and hit FastAPI (`zeocore[http]`).
- [examples/mcp_server_usage.py](examples/mcp_server_usage.py): Expose a
  tool as an MCP server (`zeocore[mcp]`).
- [examples/explicit_plugin_loading_example.py](examples/explicit_plugin_loading_example.py):
  Discover and load plugins without import-time side effects.
- [examples/notion_usage.py](examples/notion_usage.py): Notion read/write,
  skip when `NOTION_TOKEN` isn't set.
- [examples/calendar_usage.py](examples/calendar_usage.py): Google
  Calendar read/write, skip when OAuth isn't configured.
- [examples/jupytext_usage.py](examples/jupytext_usage.py): Script ↔
  notebook round-trip.
- [examples/ffmpeg_usage.py](examples/ffmpeg_usage.py): Probe, transcode,
  thumbnail a synthetic test video.

## Package surface (import paths)

- `zeo_core` (top level): `BaseZeoTool`, `ToolContext`, `ZeoToolProtocol`,
  `CapabilityResult`, and the three optional mixins
  (`IntegrationEnabledMixin`, `LifecycleMixin`, `ToolEnvInitializerMixin`)
  — the tool-authoring surface, re-exported for single-import
  convenience. Everything else below is its own import; this top level
  intentionally does not re-export config/core/integrations/modules.
- `zeo_core.tools`: same tool-authoring surface as the top level (the
  canonical, explicit path), plus `@capability`, `CapabilityRegistry`,
  `invoke_sync`/`invoke_async`, and `tool_to_capability`. Do not import
  from `zeo_core.tools.mixins.*` submodules directly.
- `zeo_core.contracts`: `CapabilityId`, `CapabilityDefinition`,
  `CapabilityManifest`, `CapabilityResult`, `CapabilityOutcome`,
  `CapabilityError`, artifact and manifest models, common enums/IDs.
  Machine-readable codes use `ZEO_<AREA>_<DETAIL>` (`ZC_` and legacy
  `QC_` accepted). Effects are declarations, not authorization.
- `zeo_core.adapters`: `adapters.http`, `adapters.mcp` (both can bind a
  capability into `OperationRegistry`), and `adapters.llm_tools`
  (OpenAI-compatible function projection; never silently weakens input
  JSON Schema).
- `zeo_core.config`: `load_config()`, `ZeoConfig` and its component
  models, YAML + environment-variable configuration loading.
- `zeo_core.core`: `core.fs` (filesystem ops), `core.paths` (path
  resolution), `core.errors` (the `ZeoError` typed exception hierarchy),
  plus MIME detection, serialization, and logging helpers.
- `zeo_core.integrations`: `google.drive` (`GoogleDriveService`),
  `google.mail` (`GoogleMailService`), `google.calendar`
  (`GoogleCalendarService`, read+write: calendars, events with date-range
  filtering, create/update/delete) — all three also re-exported one level
  shallower at `zeo_core.integrations.google` — plus `github`, `notion`
  (read + write, bearer-token auth), `pandoc`, `jupytext`
  (`script_to_notebook`/`notebook_to_script`), `ffmpeg` (`probe`,
  `convert`, `transcode_h264`, `extract_audio`, `thumbnail`, wrapping the
  org's `ffmpeg-zeo` package, Python >=3.12 required by that package),
  and `llms` (OpenAI/Anthropic/Ollama clients behind one
  `LLMProviderProtocol` — `chat()`, `count_tokens()`, `.model`;
  `LLMOptions.tools` for tool-calling and `LLMOptions.cache_system_prompt`
  for Anthropic prompt caching — see GET-STARTED.md for the one known
  gap: tool_use response blocks aren't parsed back into structured
  output yet). `supabase` is shipped (Database, Auth, Storage, Edge Functions and Realtime);
  raw SQL and Vault plaintext access are excluded. Do not infer BigQuery or a
  general SQLite integration from the internal SQLite effect broker.
- `zeo_core.contract_pack`: `PACK_VERSION` / `PACK_SCHEMA` for ecosystem
  consumption tests; does not import `sovereign_agent`.
- `zeo_core.modules`: Plugin discovery and explicit-loading registry.
- `zeo_core.prompt`: Prompt template selection and enhancement.
- `zeo_core.tools.catalog`: in-tree **reference** capabilities, not a
  public API. `zeo_core.tools.compat.sovereign_style_capability` is
  transitional, not canonical.

## 0.10.0 integration and authoring additions

- `zeo_core.integrations.hubspot` and `.kit`: registered marketing capabilities;
  [HubSpot](docs/tutorials/hubspot-marketing.md) and [Kit](docs/tutorials/kit-marketing.md).
  Simulated examples do not send email. Live sends require explicit authorization.
- `zeo_core.integrations.environments.IntegrationEnvironment`: explicit test or
  production state and credential selection. Start with [account setup](docs/integrations/README.md).
- `zeo_core.integrations.hosted`: `ServiceResolver`, `ServiceRequirement`,
  `ExecutionProfile`, `Ready`; profiles require explicit placement and services.
- `zeo_core.integrations.gemini`: `ImageGenerationService`, `ImageGenerationRequest`,
  `ImageArtifactStore`; admitted connections, host signatures and Keychain custody.
  Request construction grants no authority. [Guide](docs/integrations/gemini-images.md).
- `zeo_core.integrations.notebook`: `NotebookExecutionRequest`, `execute_notebook`;
  trusted local Python, a fresh kernel, time/output bounds and failure receipts.
  It is not a security sandbox. [Guide](docs/integrations/notebook-execution.md).
- [Authoring reference](docs/integrations/authoring-reference.md): conversion and
  staging receipts; staging does not upload or publish.

## Conventions worth knowing before you guess

- Tools report expected failure/skip conditions via
  `CapabilityResult.ok()` / `.skip()` / `.unavailable()` / `.fail()` /
  `.fail_from_exc()` — not by raising. Fine-grained `CapabilityOutcome`
  maps onto success/skipped/error. Raise only for genuinely exceptional
  cases, using the `zeo_core.core.errors` `ZeoError` family.
- `load_config()` with no argument never raises, even in a directory with
  no config file anywhere — it falls back to built-in defaults. It only
  raises `ZeoConfigurationError` when given an *explicit* path that
  doesn't exist.
- Optional integrations are pip extras (see README.md's extras table);
  importing an integration's service class before installing its extra
  fails at the point the extra's third-party package is actually used,
  not always at import time — check the specific submodule.
- Full type coverage: `mypy --strict` is clean across `src/` and `tests/`
  (this is the gate, not aspirational) — trust the type signatures.

## Machine-readable interfaces

- `py.typed` is shipped (PEP 561) — mypy/pyright get real types with no
  stub package needed.
- `zeo_core.adapters.http`'s FastAPI app exposes an OpenAPI schema at the
  usual FastAPI routes (`/openapi.json`) when that adapter is running;
  there is no static, pre-generated OpenAPI/JSON-Schema artifact checked
  into this repo as of this writing.
