contract4agents 0.1.0__tar.gz

contract4agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

contract4agents-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.1
+Name: contract4agents
+Version: 0.1.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
+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, allowed capabilities, policies, guards, assertions, and output contract. The compiler turns that source into prompts, provider-neutral manifests, JSON Schemas, 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.
+- `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.
+- `docs/implementation/roadmap.md` tracks the active backlog for VISION gaps that are not implemented yet.
+
+## What's Included
+
+- `contract4agents` Python package
+- `contract4agents` Click CLI
+- Lark-backed parser
+- semantic analyzer
+- 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 compile examples/incident-command --out .contract/build
+pdm run contract4agents visualize examples/incident-command --out .contract/build/visualization
+pdm run contract4agents eval tests/fixtures/contract_projects/ops-desk-lab
+pdm run docs-check
+pdm run validate
+```
+
+The `examples/incident-command` project is the public walkthrough fixture for check, compile, and visualization. The eval command currently uses the richer `tests/fixtures/contract_projects/ops-desk-lab` fixture because the reusable fixture runner expects a `fixture.json` project.
+
+## 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`.

contract4agents-0.1.0/README.md

@@ -0,0 +1,76 @@
+# 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, allowed capabilities, policies, guards, assertions, and output contract. The compiler turns that source into prompts, provider-neutral manifests, JSON Schemas, 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.
+- `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.
+- `docs/implementation/roadmap.md` tracks the active backlog for VISION gaps that are not implemented yet.
+
+## What's Included
+
+- `contract4agents` Python package
+- `contract4agents` Click CLI
+- Lark-backed parser
+- semantic analyzer
+- 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 compile examples/incident-command --out .contract/build
+pdm run contract4agents visualize examples/incident-command --out .contract/build/visualization
+pdm run contract4agents eval tests/fixtures/contract_projects/ops-desk-lab
+pdm run docs-check
+pdm run validate
+```
+
+The `examples/incident-command` project is the public walkthrough fixture for check, compile, and visualization. The eval command currently uses the richer `tests/fixtures/contract_projects/ops-desk-lab` fixture because the reusable fixture runner expects a `fixture.json` project.
+
+## 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`.

contract4agents-0.1.0/pyproject.toml

@@ -0,0 +1,141 @@
+[build-system]
+requires = [
+    "pdm-backend>=2.4.9",
+]
+build-backend = "pdm.backend"
+
+[project]
+name = "contract4agents"
+dynamic = []
+description = "Typed declarative contracts for AI agent systems."
+authors = [
+    { name = "B.T. Franklin", email = "brandon.franklin@gmail.com" },
+]
+dependencies = [
+    "click>=8.4.1",
+    "lark>=1.3.1",
+    "jsonschema>=4.26.0",
+    "promptdown>=1.1.6",
+]
+requires-python = ">=3.11"
+readme = "README.md"
+keywords = [
+    "agents",
+    "contracts",
+    "evals",
+    "llm",
+    "openai",
+    "tooling",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "Topic :: File Formats",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Code Generators",
+]
+version = "0.1.0"
+
+[project.license]
+file = "LICENSE"
+
+[project.urls]
+Homepage = "https://github.com/btfranklin/contract4agents"
+Issues = "https://github.com/btfranklin/contract4agents/issues"
+Changelog = "https://github.com/btfranklin/contract4agents/releases"
+Repository = "https://github.com/btfranklin/contract4agents.git"
+
+[project.scripts]
+contract4agents = "contract4agents.cli:main"
+
+[project.optional-dependencies]
+openai = [
+    "openai>=2.44.0",
+    "openai-agents>=0.17.7",
+]
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.version]
+source = "scm"
+
+[tool.pdm.build]
+package-dir = "src"
+excludes = [
+    "examples/**",
+    "tests/**",
+]
+
+[tool.pdm.scripts]
+test = "pytest"
+"test:unit" = "pytest tests/unit --cov=contract4agents --cov-report=term-missing --cov-fail-under=90"
+"test:integration" = "pytest tests/integration"
+"test:openai-live" = "pytest tests/integration/test_openai_live.py"
+"test:agent-fixture" = "pytest tests/integration/test_ops_desk_fixture.py"
+"test:openai-agent-live" = "pytest tests/integration/test_openai_agent_live.py"
+docs-check = "python -m contract4agents docs-check"
+lint = "ruff check src tests examples"
+typecheck = "mypy src"
+contract4agents = "python -m contract4agents"
+
+[tool.pdm.scripts.validate]
+composite = [
+    "lint",
+    "typecheck",
+    "docs-check",
+    "test",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+markers = [
+    "integration: tests that may require optional services or credentials",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true
+warn_return_any = true
+files = [
+    "src",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.18",
+    "mypy>=2.1.0",
+    "pytest-asyncio>=1.4.0",
+    "types-jsonschema>=4.26.0.20260518",
+]
+openai = [
+    "openai>=2.44.0",
+    "openai-agents>=0.17.7",
+]

contract4agents-0.1.0/src/contract4agents/__init__.py

@@ -0,0 +1,7 @@
+"""Contract4Agents Python package."""
+
+from contract4agents.compiler import compile_project
+from contract4agents.parser import parse_file, parse_project
+from contract4agents.semantics import analyze_project
+
+__all__ = ["analyze_project", "compile_project", "parse_file", "parse_project"]

contract4agents-0.1.0/src/contract4agents/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for the Contract4Agents CLI."""
+
+from contract4agents.cli import main
+
+if __name__ == "__main__":
+    main()

contract4agents-0.1.0/src/contract4agents/adapters/openai.py

@@ -0,0 +1,169 @@
+"""OpenAI Agents SDK adapter.
+
+The adapter is intentionally thin: Contract4Agents compiles to provider-neutral
+manifests first, and this module projects those manifests onto OpenAI's SDK.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from contract4agents.compiler import AgentManifest
+from contract4agents.runtime import TraceRecorder
+
+_RunHooksBase: type[Any]
+try:
+    from agents import RunHooks as _ImportedRunHooks
+
+    _RunHooksBase = _ImportedRunHooks
+except Exception:  # noqa: BLE001 - optional adapter import boundary.
+    _RunHooksBase = object
+
+
+@dataclass(frozen=True)
+class OpenAIAdapterResult:
+    final_output: Any
+    last_agent: str | None
+    raw_result: Any
+
+
+class OpenAIAdapterUnavailable(RuntimeError):
+    pass
+
+
+def openai_tool_name(contract_name: str) -> str:
+    """Convert a Contract4Agents capability name into an OpenAI-safe tool name."""
+    return contract_name.replace(".", "__")
+
+
+def contract_tool_name(openai_name: str) -> str:
+    """Convert a generated OpenAI tool name back into the Contract4Agents capability name."""
+    return openai_name.replace("__", ".")
+
+
+class OpenAITraceHooks(_RunHooksBase):  # type: ignore[misc]
+    """Minimal hook object that normalizes Agents SDK lifecycle events to Contract4Agents traces."""
+
+    def __init__(self, trace: TraceRecorder) -> None:
+        super().__init__()
+        self.trace = trace
+
+    async def on_agent_start(self, _context: Any, agent: Any) -> None:
+        self.trace.record("agent.started", agent=getattr(agent, "name", str(agent)))
+
+    async def on_agent_end(self, _context: Any, agent: Any, output: Any) -> None:
+        self.trace.record("agent.completed", agent=getattr(agent, "name", str(agent)), output=_serializable(output))
+
+    async def on_handoff(self, _context: Any, from_agent: Any, to_agent: Any) -> None:
+        self.trace.record(
+            "agent.handoff",
+            from_agent=getattr(from_agent, "name", str(from_agent)),
+            to_agent=getattr(to_agent, "name", str(to_agent)),
+        )
+
+    async def on_tool_start(self, _context: Any, agent: Any, tool: Any) -> None:
+        self.trace.record(
+            "tool.started",
+            agent=getattr(agent, "name", str(agent)),
+            tool=contract_tool_name(getattr(tool, "name", str(tool))),
+        )
+
+    async def on_tool_end(self, _context: Any, agent: Any, tool: Any, result: str) -> None:
+        self.trace.record(
+            "tool.completed",
+            agent=getattr(agent, "name", str(agent)),
+            tool=contract_tool_name(getattr(tool, "name", str(tool))),
+            result=_serializable(result),
+        )
+
+    async def on_llm_start(self, _context: Any, agent: Any, _system_prompt: str | None, input_items: list[Any]) -> None:
+        self.trace.record("llm.started", agent=getattr(agent, "name", str(agent)), input_count=len(input_items))
+
+    async def on_llm_end(self, _context: Any, agent: Any, _response: Any) -> None:
+        self.trace.record("llm.completed", agent=getattr(agent, "name", str(agent)))
+
+
+def build_openai_agent(
+    manifest: AgentManifest,
+    instructions: str,
+    tools: list[Any] | None = None,
+    handoffs: list[Any] | None = None,
+    output_type: Any | None = None,
+    hooks: Any | None = None,
+    input_guardrails: list[Any] | None = None,
+) -> Any:
+    try:
+        from agents import Agent
+    except Exception as exc:  # noqa: BLE001 - optional adapter import boundary.
+        raise OpenAIAdapterUnavailable("openai-agents is not installed") from exc
+    kwargs: dict[str, Any] = {
+        "name": manifest["agent"],
+        "instructions": instructions,
+        "model": manifest.get("model", "gpt-5.5"),
+        "tools": tools or [],
+        "handoffs": handoffs or [],
+    }
+    if output_type is not None:
+        kwargs["output_type"] = output_type
+    if hooks is not None:
+        kwargs["hooks"] = hooks
+    if input_guardrails is not None:
+        kwargs["input_guardrails"] = input_guardrails
+    return Agent(**kwargs)
+
+
+async def run_openai_agent(
+    agent: Any,
+    user_input: str,
+    *,
+    context: Any | None = None,
+    max_turns: int | None = 10,
+    hooks: Any | None = None,
+) -> OpenAIAdapterResult:
+    try:
+        from agents import Runner
+    except Exception as exc:  # noqa: BLE001 - optional adapter import boundary.
+        raise OpenAIAdapterUnavailable("openai-agents is not installed") from exc
+    result = await Runner.run(agent, user_input, context=context, max_turns=max_turns, hooks=hooks)
+    last_agent = getattr(getattr(result, "last_agent", None), "name", None)
+    return OpenAIAdapterResult(getattr(result, "final_output", None), last_agent, result)
+
+
+class OpenAISemanticJudge:
+    def __init__(self, model: str = "gpt-5.5", api_key_env: str = "OPENAI_API_KEY") -> None:
+        self.model = model
+        self.api_key_env = api_key_env
+
+    async def judge(self, *, output: dict[str, Any], criterion: str) -> bool:
+        if not os.getenv(self.api_key_env):
+            raise OpenAIAdapterUnavailable(f"{self.api_key_env} is not set")
+        try:
+            from openai import AsyncOpenAI
+        except Exception as exc:  # noqa: BLE001 - optional adapter import boundary.
+            raise OpenAIAdapterUnavailable("openai package is not installed") from exc
+        client = AsyncOpenAI()
+        response = await client.responses.create(
+            model=self.model,
+            input=[
+                {
+                    "role": "system",
+                    "content": "Return only PASS or FAIL. Evaluate whether the output satisfies the criterion.",
+                },
+                {
+                    "role": "user",
+                    "content": f"Criterion: {criterion}\nOutput: {output}",
+                },
+            ],
+        )
+        text = getattr(response, "output_text", "")
+        return str(text).strip().upper() == "PASS"
+
+
+def _serializable(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump()
+    if isinstance(value, dict | list | str | int | float | bool) or value is None:
+        return value
+    return str(value)

contract4agents-0.1.0/src/contract4agents/ast.py

@@ -0,0 +1,135 @@
+"""AST nodes for Contract4Agents source files."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+
+@dataclass(frozen=True)
+class SourceSpan:
+    path: Path
+    line: int
+    column: int = 1
+
+    def display(self) -> str:
+        return f"{self.path}:{self.line}:{self.column}"
+
+
+@dataclass(frozen=True)
+class FieldDef:
+    name: str
+    type_name: str
+    nullable: bool = False
+    default: str | None = None
+    span: SourceSpan | None = None
+
+    @property
+    def normalized_type(self) -> str:
+        return self.type_name.rstrip("?").strip()
+
+
+@dataclass(frozen=True)
+class TypeDef:
+    name: str
+    fields: list[FieldDef]
+    span: SourceSpan
+
+
+Permission = Literal["available", "preapproved", "requires_approval", "denied", "sandboxed"]
+UseKind = Literal["tool", "agent", "datasource"]
+
+
+@dataclass(frozen=True)
+class UseDecl:
+    kind: UseKind
+    name: str
+    source: str
+    permission: Permission = "available"
+    span: SourceSpan | None = None
+
+
+@dataclass(frozen=True)
+class DatasourceDef:
+    name: str
+    python: str
+    requires: list[str]
+    produces: str
+    render: str = "markdown"
+    cache: str = "run"
+    span: SourceSpan | None = None
+
+
+@dataclass(frozen=True)
+class AgentDef:
+    name: str
+    parameters: list[FieldDef]
+    return_type: str
+    uses: list[UseDecl]
+    attributes: dict[str, Any]
+    span: SourceSpan
+
+    def list_attr(self, key: str) -> list[str]:
+        value = self.attributes.get(key, [])
+        return value if isinstance(value, list) else []
+
+    def text_attr(self, key: str) -> str:
+        value = self.attributes.get(key, "")
+        return value if isinstance(value, str) else ""
+
+
+@dataclass(frozen=True)
+class EvalCase:
+    name: str
+    agent: str
+    givens: dict[str, str]
+    expects: list[str]
+    semantic_expects: list[str]
+    span: SourceSpan
+
+
+@dataclass(frozen=True)
+class MonitorDef:
+    name: str
+    agent: str
+    severity: str
+    condition: str
+    expectation: str
+    span: SourceSpan
+
+
+@dataclass
+class ContractModule:
+    path: Path
+    types: list[TypeDef] = field(default_factory=list)
+    datasources: list[DatasourceDef] = field(default_factory=list)
+    agents: list[AgentDef] = field(default_factory=list)
+    evals: list[EvalCase] = field(default_factory=list)
+    monitors: list[MonitorDef] = field(default_factory=list)
+
+
+@dataclass
+class ContractProject:
+    root: Path
+    modules: list[ContractModule]
+
+    @property
+    def types(self) -> dict[str, TypeDef]:
+        return {item.name: item for module in self.modules for item in module.types}
+
+    @property
+    def datasources(self) -> dict[str, DatasourceDef]:
+        return {item.name: item for module in self.modules for item in module.datasources}
+
+    @property
+    def agents(self) -> dict[str, AgentDef]:
+        return {item.name: item for module in self.modules for item in module.agents}
+
+    @property
+    def evals(self) -> list[EvalCase]:
+        return [item for module in self.modules for item in module.evals]
+
+    @property
+    def monitors(self) -> list[MonitorDef]:
+        return [item for module in self.modules for item in module.monitors]