Metadata-Version: 2.4
Name: tai42-contract
Version: 4.1.0
Summary: Pure interface contracts (protocols, ABCs, models) for the TAI ecosystem. No logic; pydantic-only at runtime.
Author-email: tai42 <oss@tai42.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://tai42.ai
Project-URL: Repository, https://github.com/tai42ai/tai42/tree/main/core/contract
Project-URL: Issues, https://github.com/tai42ai/tai42/issues
Project-URL: Changelog, https://github.com/tai42ai/tai42/blob/main/core/contract/CHANGELOG.md
Keywords: protocol,contract,interface,typing,mcp,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic>=2.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pyright>=1.1.389; extra == "dev"
Requires-Dist: fastmcp>=3.4.7; extra == "dev"
Requires-Dist: langchain-core>=1; extra == "dev"
Requires-Dist: starlette>=0.40; extra == "dev"
Requires-Dist: mcp>=1; extra == "dev"
Dynamic: license-file

# tai42-contract

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

Pure interface contracts for the TAI ecosystem: the protocols, ABCs, pydantic
models, and enums every other package builds against. At runtime this package
imports nothing but `pydantic`, and its behaviour is limited to a narrow
whitelisted surface — the `tai42_app` forwarding handle, model-level
validators/normalizers, the storage path guard, and `Agent`'s default
`astream`/terminal-drain; everything else is a pydantic model, Protocol, ABC, or
enum. Vendor types (fastmcp, langchain, starlette, mcp) appear only inside
`TYPE_CHECKING` blocks, so they are never loaded when the code runs.

## Position in the ecosystem

TAI is an open-source runtime for MCP tools, agents, and workflows — the server
that hosts a capability and supplies the operational layer around it (manifest
loading, access control, OAuth connectors, background execution, monitoring,
storage, and human-in-the-loop steps). Everything plugs in against the
interfaces this package defines.

Four packages; each depends only on the ones to its left:

```
                     tai42-kit  <--.
                   /  (helpers)     \
tai42-contract  <-+                  +--  tai42-skeleton
  (interfaces)     \                /    (the server)
                     tai42-cli  <--'
               (the remote client)
```

`tai42-contract` is the leaf: it depends on no other tai-* package, so anything —
the skeleton, the CLI, a plugin, a helper — can import it without pulling in an
implementation.

## Install

Requires **Python 3.13+**. Install from PyPI into the environment that runs the
server. Usually pulled in transitively via `tai42-kit` / `tai42-skeleton`, but it
installs directly too:

```bash
uv add tai42-contract
```

Or from source — clone this repo and add it as an editable dependency:

```bash
git clone https://github.com/tai42ai/tai42   # next to your app checkout
cd /path/to/your/app
uv add --editable ../tai42/core/contract
```

## Development

```bash
uv venv --python 3.13
uv pip install --no-sources --editable ".[dev]"   # pydantic + tooling + vendor libs (for pyright)
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync pyright
uv run --no-sync pytest --cov --cov-report=term-missing                           # self-contained contract tests
```

## Documentation

The whole platform — concepts, guides, and the generated reference — lives in
the unified documentation site:

- Layering & the contract/kit/cli/skeleton split: https://tai42.ai/concepts/layering
- Python SDK reference (this package's public API): https://tai42.ai/reference/python-sdk

## License

Apache-2.0. See `LICENSE` and `NOTICE`.
