contract4agents 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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]

contract4agents/cli.py

@@ -0,0 +1,143 @@
+"""Click CLI for Contract4Agents."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from contract4agents.compiler import build_artifacts, compile_project
+from contract4agents.diagnostics import ContractError, raise_if_errors
+from contract4agents.docscheck import check_docs
+from contract4agents.fixtures import FixtureReport, run_fixture_project_sync
+from contract4agents.monitor import MonitorRule, run_monitors
+from contract4agents.parser import parse_project
+from contract4agents.runtime._trace_io import TraceFileError, load_trace_jsonl
+from contract4agents.semantics import analyze_project
+from contract4agents.visualization import build_visualization_graph, write_visualization_artifacts
+
+
+@click.group()
+def main() -> None:
+    """Compile, validate, and evaluate Contract4Agents projects."""
+
+
+@main.command()
+@click.argument("root", type=click.Path(path_type=Path), default=".", required=False)
+def check(root: Path) -> None:
+    """Parse and semantically validate a Contract4Agents project."""
+    try:
+        project = parse_project(root)
+        result = analyze_project(project)
+        for diagnostic in result.diagnostics:
+            click.echo(diagnostic.format(), err=diagnostic.severity == "error")
+        if not result.ok:
+            raise click.ClickException("Contract4Agents check failed")
+        click.echo("Contract4Agents check passed")
+    except ContractError as exc:
+        _print_contract_error(exc)
+
+
+@main.command("compile")
+@click.argument("root", type=click.Path(path_type=Path), default=".", required=False)
+@click.option("--out", "output_dir", type=click.Path(path_type=Path), default=".contract/build")
+@click.option("--check", "check_mode", is_flag=True, help="Fail if generated artifacts are stale.")
+def compile_cmd(root: Path, output_dir: Path, check_mode: bool) -> None:
+    """Compile a Contract4Agents project into provider-neutral artifacts."""
+    try:
+        compile_project(root, output_dir, check=check_mode)
+        click.echo("Contract4Agents compile passed")
+    except ContractError as exc:
+        _print_contract_error(exc)
+
+
+@main.command("visualize")
+@click.argument("root", type=click.Path(path_type=Path), default=".", required=False)
+@click.option("--out", "output_dir", type=click.Path(path_type=Path), default=".contract/build/visualization")
+def visualize_cmd(root: Path, output_dir: Path) -> None:
+    """Generate static HTML visualization artifacts.
+
+    ROOT defaults to the current directory. The default output directory is
+    .contract/build/visualization.
+    """
+    try:
+        project = parse_project(root)
+        raise_if_errors(analyze_project(project).diagnostics)
+        artifacts = build_artifacts(project)
+        graph = build_visualization_graph(project, artifacts)
+        write_visualization_artifacts(graph, output_dir)
+        click.echo(f"Contract4Agents visualization written to {output_dir}")
+    except ContractError as exc:
+        _print_contract_error(exc)
+
+
+@main.command("eval")
+@click.argument("root", type=click.Path(path_type=Path), default=".", required=False)
+def eval_cmd(root: Path) -> None:
+    """Run local evals for a fixture.json project."""
+    if not (root / "fixture.json").exists():
+        raise click.ClickException("Contract4Agents eval requires ROOT/fixture.json")
+    try:
+        report = run_fixture_project_sync(project_root=root, run_root=root / ".contract" / "runs" / "last")
+    except Exception as exc:
+        raise click.ClickException(f"Contract4Agents fixture eval failed: {exc}") from exc
+    _print_fixture_report(report)
+    if not report.passed:
+        raise click.ClickException("Contract4Agents eval failed")
+
+
+def _print_fixture_report(report: FixtureReport) -> None:
+    click.echo(f"Fixture eval {'passed' if report.passed else 'failed'}: {len(report.starts)} starts")
+    for start in report.starts:
+        status = "PASS" if start.passed and not start.monitor_violations else "FAIL"
+        click.echo(f"{status} {start.start_id}")
+        for failure in start.failures:
+            click.echo(f"  {failure}")
+        for violation in start.monitor_violations:
+            click.echo(f"  monitor: {violation}")
+        for skipped in start.skipped_semantic:
+            click.echo(f"  semantic skipped: {skipped}")
+
+
+@main.command()
+@click.argument("root", type=click.Path(path_type=Path), default=".", required=False)
+@click.option("--trace", "trace_path", type=click.Path(path_type=Path), required=True, help="Trace JSONL file.")
+def monitor(root: Path, trace_path: Path) -> None:
+    """Run project monitors against a trace JSONL file."""
+    artifacts = compile_project(root)
+    try:
+        trace = load_trace_jsonl(trace_path)
+    except TraceFileError as exc:
+        raise click.ClickException(str(exc)) from exc
+    rules = [
+        MonitorRule(item["name"], item["agent"], item["severity"], item["when"], item["expect"])
+        for item in artifacts["monitors"]
+    ]
+    violations = run_monitors(rules, trace)
+    for violation in violations:
+        click.echo(f"{violation.severity.upper()} {violation.rule}: {violation.message}")
+    if violations:
+        raise click.ClickException("Contract4Agents monitor failed")
+    click.echo("Contract4Agents monitor passed")
+
+
+@main.command("docs-check")
+@click.argument("root", type=click.Path(path_type=Path), default=".", required=False)
+def docs_check(root: Path) -> None:
+    """Check required documentation files and local markdown links.
+
+    ROOT defaults to the current directory.
+    """
+    diagnostics = check_docs(root)
+    for diagnostic in diagnostics:
+        click.echo(diagnostic.format(), err=True)
+    if diagnostics:
+        raise click.ClickException("Docs check failed")
+    click.echo("Docs check passed")
+
+
+def _print_contract_error(exc: ContractError) -> None:
+    for diagnostic in exc.diagnostics:
+        click.echo(diagnostic.format(), err=True)
+    sys.exit(1)