Metadata-Version: 2.1
Name: contract4agents
Version: 0.3.0
Summary: Typed declarative contracts for AI agent systems.
Keywords: agents,contracts,evals,llm,openai,tooling
Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
License: MIT License
         
         Copyright (c) 2026, B.T. Franklin
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Topic :: File Formats
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Code Generators
Project-URL: Homepage, https://github.com/btfranklin/contract4agents
Project-URL: Issues, https://github.com/btfranklin/contract4agents/issues
Project-URL: Changelog, https://github.com/btfranklin/contract4agents/releases
Project-URL: Repository, https://github.com/btfranklin/contract4agents.git
Requires-Python: >=3.11
Requires-Dist: click>=8.4.1
Requires-Dist: lark>=1.3.1
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: promptdown>=1.1.6
Requires-Dist: pydantic>=2.13.4
Provides-Extra: openai
Requires-Dist: openai>=2.44.0; extra == "openai"
Requires-Dist: openai-agents>=0.17.7; extra == "openai"
Description-Content-Type: text/markdown

# Contract4Agents

![Contract4Agents banner](https://raw.githubusercontent.com/btfranklin/contract4agents/main/.github/social%20preview/contract4agents_social_preview.jpg "Contract4Agents")

Contract4Agents is a typed declarative language and local toolchain for defining AI agents as inspectable contracts.

The source artifact is a `.contract` file. It describes an agent's callable interface, context requirements, allowed capabilities, policies, guards, assertions, and output contract. The compiler turns that source into prompts, provider-neutral manifests, JSON Schemas, guard plans, eval packs, monitor rules, and visualization artifacts.

Contract4Agents includes the compiler, CLI, local fixtures, monitor checks, runtime primitives, and provider adapters needed to use those contracts beside a host agent application.

Start here:

- `docs/tutorials/using-contract4agents-with-an-agent-app.md` explains how to
  use Contract4Agents beside an existing agent SDK implementation.
- `VISION.md` explains the concept and why it exists.
- `examples/incident-command/README.md` is the most concrete first read: it
  explains what users write, what the files mean, and what artifacts are
  generated.
- `examples/multi-lens-research/README.md` shows a complex research team split
  into focused expert lenses.
- `examples/market-research-brief/README.md` shows document-driven market
  research against dated current-fact snapshots, including an OpenAI hosted
  web-search declaration.
- `examples/README.md` explains the reusable pattern for future examples.
- `docs/index.md` is the documentation map.
- `docs/examples/incident-command-walkthrough.md` walks through the clone-only example.
- `docs/research/agent-sdk-pattern-survey.md` captures the cross-SDK patterns Contract4Agents should preserve.
- `docs/decisions/accepted-decisions.md` records choices that should not be reopened casually.

## What's Included

- `contract4agents` Python package
- `contract4agents` Click CLI
- Lark-backed parser
- semantic analyzer
- static child-agent context dependency checks
- source-owned capability registry and strict host-code drift checks
- run specs for host-owned workflow trace and stage-output expectations
- JSON Schema and provider-neutral manifest compiler
- local fake-tool and datasource runtime primitives
- eval and monitor runners
- static project visualization
- first OpenAI adapter and semantic judge adapter
- clone-only `Incident Command` example backed by SQLite fake data

## Development Setup

```bash
pdm install
pdm run contract4agents --help
```

## Useful Commands

```bash
pdm run contract4agents check examples/incident-command
pdm run contract4agents check examples/incident-command --strict-drift
pdm run contract4agents compile examples/incident-command --out .contract/build
pdm run contract4agents visualize examples/incident-command --out .contract/build/visualization
pdm run contract4agents eval examples/incident-command
pdm run docs-check
pdm run validate
```

The `examples/incident-command` project is the public walkthrough fixture for check, compile, visualization, and eval. The richer `tests/fixtures/contract_projects/ops-desk-lab` fixture remains available for internal edge-case coverage.

## OpenAI Adapter Checks

The normal validation suite does not call external APIs. Live OpenAI checks are opt-in:

```bash
CONTRACT4AGENTS_RUN_OPENAI_LIVE=1 pdm run test:openai-live
CONTRACT4AGENTS_RUN_OPENAI_AGENT_LIVE=1 pdm run test:openai-agent-live
```

Those commands require `OPENAI_API_KEY` in the environment or in the ignored local `.env` file.

## License

MIT. See `LICENSE`.
