agent-grammar 0.1.2__py3-none-any.whl

agent_grammar/__init__.py

@@ -0,0 +1,7 @@
+"""agent-grammar: Test-gated AI agent workflow documentation for HTTP APIs."""
+
+from agent_grammar.testing import AgentTestClient, step_boundary, workflow
+
+__version__ = "0.1.2"
+
+__all__ = ["AgentTestClient", "step_boundary", "workflow", "__version__"]

agent_grammar/_context.py

@@ -0,0 +1,65 @@
+"""ContextVar-based recorder lifecycle for the workflow capture pipeline."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+
+from agent_grammar._models import (
+    Binding,
+    BoundaryStep,
+    HttpStep,
+    WorkflowRecord,
+    slugify,
+)
+
+
+class WorkflowRecorder:
+    """Mutable builder collecting steps as a decorated test runs."""
+
+    def __init__(
+        self,
+        name: str,
+        intent: str,
+        bindings: list[Binding] | None = None,
+    ) -> None:
+        self.name = name
+        self.intent = intent
+        self.bindings: list[Binding] = list(bindings) if bindings else []
+        self.steps: list[HttpStep | BoundaryStep] = []
+        self.complete: bool = False
+
+    def add_http_step(self, step: HttpStep) -> None:
+        self.steps.append(step)
+
+    def add_boundary_step(self, step: BoundaryStep) -> None:
+        self.steps.append(step)
+
+    def mark_complete(self) -> None:
+        self.complete = True
+
+    def build(self) -> WorkflowRecord:
+        return WorkflowRecord(
+            name=self.name,
+            slug=slugify(self.name),
+            intent=self.intent,
+            bindings=list(self.bindings),
+            steps=list(self.steps),
+        )
+
+
+_current_recorder: ContextVar[WorkflowRecorder | None] = ContextVar(
+    "agent_grammar_recorder", default=None
+)
+
+
+def get_active_recorder() -> WorkflowRecorder | None:
+    return _current_recorder.get()
+
+
+def set_active_recorder(recorder: WorkflowRecorder | None) -> Any:
+    return _current_recorder.set(recorder)
+
+
+def reset_recorder(token: Any) -> None:
+    _current_recorder.reset(token)

agent_grammar/_models.py

@@ -0,0 +1,50 @@
+"""Core data models for workflow recording and rendering."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Union
+
+
+@dataclass
+class HttpStep:
+    method: str
+    path: str
+    request_json: Any | None
+    status_code: int
+    response_json: Any | None
+    domain: str = "Core Service"
+
+
+@dataclass
+class BoundaryStep:
+    domain: str
+    name: str
+
+
+Step = Union[HttpStep, BoundaryStep]
+
+
+@dataclass
+class Binding:
+    source: str
+    target: str
+
+
+@dataclass
+class WorkflowRecord:
+    name: str
+    slug: str
+    intent: str
+    bindings: list[Binding] = field(default_factory=list)
+    steps: list[Step] = field(default_factory=list)
+
+
+_SLUG_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(name: str) -> str:
+    lowered = name.strip().lower()
+    collapsed = _SLUG_NON_ALNUM.sub("_", lowered)
+    return collapsed.strip("_")

agent_grammar/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entry points for agent-grammar."""

agent_grammar/cli/export.py

@@ -0,0 +1,92 @@
+"""``agent-grammar export-agent-docs`` subcommand."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+PLATFORMS = ("cursor", "claude", "copilot", "gemini")
+
+
+def _build_environment() -> Environment:
+    return Environment(
+        loader=PackageLoader("agent_grammar", "templates"),
+        autoescape=select_autoescape(default=False),
+        trim_blocks=False,
+        lstrip_blocks=False,
+        keep_trailing_newline=True,
+    )
+
+
+@click.command("export-agent-docs")
+@click.option(
+    "--base-url",
+    required=True,
+    help="Production base URL of the API (e.g. https://api.example.com).",
+)
+@click.option(
+    "--api-version",
+    default="v1",
+    show_default=True,
+    help="API version namespace (used in the fetch URL and local file path).",
+)
+@click.option(
+    "--output-dir",
+    default="./agent-docs",
+    show_default=True,
+    type=click.Path(file_okay=False, dir_okay=True),
+    help="Directory to write the platform-specific system prompts.",
+)
+@click.option(
+    "--workflows-path",
+    default=None,
+    help=(
+        "Local file path where the agent should cache workflows. "
+        "Default: .agent/workflows_{version}.md"
+    ),
+)
+@click.option(
+    "--platform",
+    "platforms",
+    multiple=True,
+    type=click.Choice(PLATFORMS),
+    default=PLATFORMS,
+    show_default=True,
+    help="Which platform rules to generate. Repeat to select multiple.",
+)
+def export_agent_docs(
+    base_url: str,
+    api_version: str,
+    output_dir: str,
+    workflows_path: str | None,
+    platforms: tuple[str, ...],
+) -> None:
+    """Generate platform-specific system prompts for API consumers."""
+    base = base_url.rstrip("/")
+    workflows_path = workflows_path or f".agent/workflows_{api_version}.md"
+    fetch_url = f"{base}/{api_version}/agent-workflows"
+
+    output = Path(output_dir)
+    output.mkdir(parents=True, exist_ok=True)
+
+    env = _build_environment()
+    context = {
+        "base_url": base,
+        "api_version": api_version,
+        "workflows_path": workflows_path,
+        "fetch_url": fetch_url,
+    }
+
+    written: list[Path] = []
+    for platform in platforms:
+        template = env.get_template(f"{platform}.md.j2")
+        rendered = template.render(**context)
+        target = output / f"{platform}-rules.md"
+        target.write_text(rendered, encoding="utf-8")
+        written.append(target)
+
+    click.echo(f"Wrote {len(written)} file(s) to {output}:")
+    for path in written:
+        click.echo(f"  - {path}")

agent_grammar/cli/main.py

@@ -0,0 +1,21 @@
+"""Top-level Click group for the ``agent-grammar`` console script."""
+
+from __future__ import annotations
+
+import click
+
+from agent_grammar import __version__
+from agent_grammar.cli.export import export_agent_docs
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="agent-grammar")
+def cli() -> None:
+    """agent-grammar: test-gated AI agent workflow documentation."""
+
+
+cli.add_command(export_agent_docs)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

agent_grammar/serve/__init__.py

@@ -0,0 +1 @@
+"""Server-side helpers for serving the compiled workflows.md."""

agent_grammar/serve/fastapi.py

@@ -0,0 +1,100 @@
+"""FastAPI/Starlette helpers: GrammarRouter and AgentTelemetryMiddleware."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse, Response
+
+logger = logging.getLogger("agent_grammar.serve")
+
+TELEMETRY_HEADER = "X-Agent-Grammar-Workflow"
+MARKDOWN_MEDIA_TYPE = "text/markdown; charset=utf-8"
+
+
+def GrammarRouter(
+    filepath: str | Path,
+    *,
+    reload: bool = False,
+):
+    """Return a FastAPI/Starlette router that serves the compiled markdown.
+
+    Args:
+        filepath: Path to the compiled workflows.md asset.
+        reload: If True, re-read the file on every request (dev mode).
+                If False, cache contents in memory at construction time.
+
+    Raises:
+        FileNotFoundError: If ``filepath`` does not exist at construction time.
+        ImportError: If FastAPI is not installed.
+    """
+    try:
+        from fastapi import APIRouter
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "GrammarRouter requires FastAPI. Install with "
+            "`pip install agent-grammar[fastapi]`."
+        ) from exc
+
+    path = Path(filepath)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"GrammarRouter: workflows file not found at {path!s}. "
+            "Did you run pytest to compile it?"
+        )
+
+    cached_content: str | None = None
+    if not reload:
+        cached_content = path.read_text(encoding="utf-8")
+
+    router = APIRouter()
+
+    @router.get("", include_in_schema=False)
+    @router.get("/", include_in_schema=False)
+    def _serve_workflows() -> PlainTextResponse:
+        if reload:
+            content = path.read_text(encoding="utf-8")
+        else:
+            assert cached_content is not None
+            content = cached_content
+        return PlainTextResponse(
+            content=content, media_type=MARKDOWN_MEDIA_TYPE
+        )
+
+    return router
+
+
+class AgentTelemetryMiddleware(BaseHTTPMiddleware):
+    """Detect requests bearing ``X-Agent-Grammar-Workflow`` and report them.
+
+    The middleware never raises from the telemetry callback — failures are
+    logged and swallowed so business traffic is unaffected.
+    """
+
+    def __init__(
+        self,
+        app,
+        on_detect: Callable[[str], None] | None = None,
+    ) -> None:
+        super().__init__(app)
+        self.on_detect = on_detect
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        workflow_id = request.headers.get(TELEMETRY_HEADER)
+        response = await call_next(request)
+        if (
+            workflow_id
+            and self.on_detect is not None
+            and 200 <= response.status_code < 300
+        ):
+            try:
+                self.on_detect(workflow_id)
+            except Exception:
+                logger.exception(
+                    "agent-grammar telemetry callback raised; ignoring."
+                )
+        return response

agent_grammar/serve/flask.py

@@ -0,0 +1,10 @@
+"""Placeholder for Flask integration (planned for v0.2)."""
+
+from __future__ import annotations
+
+
+def GrammarBlueprint(*args, **kwargs):  # pragma: no cover
+    raise NotImplementedError(
+        "Flask support is planned for v0.2. Use the FastAPI integration "
+        "in `agent_grammar.serve.fastapi` for now."
+    )

agent_grammar/templates/claude.md.j2

@@ -0,0 +1,22 @@
+# CLAUDE.md — API Integration Directives
+
+You are Claude, acting as an expert integration engineer. When the user asks you to write code that calls our services, you MUST follow the verified workflow grammar for the target API version below.
+
+## Target API Version: {{ api_version }}
+*(If the user explicitly requests a different version, update the URL and local file path accordingly.)*
+
+## Mandatory Pre-flight Synchronization
+Before generating any integration code:
+
+1. Check whether `{{ workflows_path }}` exists in the workspace.
+2. If it does not exist (or is stale), run:
+   ```bash
+   mkdir -p $(dirname {{ workflows_path }}) && curl -s -o {{ workflows_path }} {{ fetch_url }}
+   ```
+3. Read `{{ workflows_path }}` end-to-end before writing any code.
+
+## Generation Rules
+- **Strict adherence:** Only use the sequences, HTTP methods, and payload structures defined in the versioned grammar. Do not invent endpoints.
+- **Scope awareness:** `[Core Service]` rows are real endpoints — call them as documented. `[External/Mocked]` rows are conceptual placeholders — write custom local logic for them.
+- **Parameter bindings:** Follow the "Precise Parameter Bindings & Payloads" table exactly. Pass response values forward as the bindings dictate.
+- **Telemetry:** Every request to our service must include the header `X-Agent-Grammar-Workflow: [Workflow-ID]`, where `[Workflow-ID]` is the slug from the workflow you're implementing.

agent_grammar/templates/copilot.md.j2

@@ -0,0 +1,20 @@
+# GitHub Copilot — Custom Instructions for API Integration
+
+You are GitHub Copilot, assisting an engineer who is writing integration code against our API. Follow the verified workflow grammar precisely.
+
+## Target API Version: {{ api_version }}
+*(If the engineer is migrating to a new version, swap the version in the URL and file path below.)*
+
+## Mandatory Pre-flight Synchronization
+1. Check whether `{{ workflows_path }}` exists locally.
+2. If absent or stale, instruct the user to run:
+   ```
+   mkdir -p $(dirname {{ workflows_path }}) && curl -s -o {{ workflows_path }} {{ fetch_url }}
+   ```
+3. Read `{{ workflows_path }}` before suggesting integration code.
+
+## Generation Rules
+- **Strict adherence:** Use only the documented sequences, HTTP methods, and payload structures.
+- **Scope awareness:** `[Core Service]` endpoints are real and must be called as documented; `[External/Mocked]` steps require local glue code.
+- **Bindings:** Honor the "Precise Parameter Bindings & Payloads" table.
+- **Telemetry:** Every generated request must include `X-Agent-Grammar-Workflow: [Workflow-ID]` so the API owner can measure agent-driven adoption.

agent_grammar/templates/cursor.md.j2

@@ -0,0 +1,17 @@
+# Agent Directives for API Integration
+
+You are an expert integration engineer. When asked to write code that interacts with our services, you MUST adhere to our verified workflow grammar for the target API version.
+
+## Target API Version: {{ api_version }}
+*(Note: If the user requests upgrading to a newer API version, update the version in the URL and local file paths below accordingly).*
+
+## Mandatory Pre-flight Synchronization
+1. Check if the file `{{ workflows_path }}` exists in the local workspace.
+2. If it does NOT exist, or is stale, you MUST execute this command in the terminal to fetch it:
+   `mkdir -p $(dirname {{ workflows_path }}) && curl -s -o {{ workflows_path }} {{ fetch_url }}`
+3. Explicitly read `{{ workflows_path }}` before writing any integration code.
+
+## Generation Rules
+* **Strict Adherence:** Only use the sequences, HTTP methods, and payload structures explicitly defined in the versioned grammar.
+* **Scope Awareness:** Distinguish between `[Core Service]` endpoints (call exactly as documented) and `[External/Mocked]` steps (write custom local logic to bridge the gap).
+* **Telemetry:** Always inject the following HTTP header into generated API client code: `X-Agent-Grammar-Workflow: [Workflow-ID]`

agent_grammar/templates/gemini.md.j2

@@ -0,0 +1,20 @@
+# Gemini Code Assist — API Integration Directives
+
+You are Gemini Code Assist. When generating code that integrates with our service, conform to the verified workflow grammar.
+
+## Target API Version: {{ api_version }}
+*(If the user upgrades versions, update the URL and local path below.)*
+
+## Mandatory Pre-flight Synchronization
+1. Verify that `{{ workflows_path }}` exists in the workspace.
+2. If it is missing or stale, run:
+   ```bash
+   mkdir -p $(dirname {{ workflows_path }}) && curl -s -o {{ workflows_path }} {{ fetch_url }}
+   ```
+3. Read `{{ workflows_path }}` before writing any integration code.
+
+## Generation Rules
+- **Strict adherence:** Only the documented sequences, methods, and payloads are valid.
+- **Scope awareness:** `[Core Service]` endpoints are real; `[External/Mocked]` rows are implementer responsibilities — write local logic for those.
+- **Bindings:** Wire request fields per the "Precise Parameter Bindings & Payloads" table.
+- **Telemetry:** Inject `X-Agent-Grammar-Workflow: [Workflow-ID]` into every request you generate.

agent_grammar/testing/__init__.py

@@ -0,0 +1,6 @@
+"""Public surface of the testing SDK."""
+
+from agent_grammar.testing.client import AgentTestClient
+from agent_grammar.testing.decorators import step_boundary, workflow
+
+__all__ = ["AgentTestClient", "step_boundary", "workflow"]

agent_grammar/testing/client.py

@@ -0,0 +1,46 @@
+"""AgentTestClient: a TestClient subclass that records HTTP traffic."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from starlette.testclient import TestClient
+
+from agent_grammar._context import get_active_recorder
+from agent_grammar._models import HttpStep
+
+
+def _safe_response_json(response: Any) -> Any | None:
+    try:
+        return response.json()
+    except (ValueError, Exception):
+        return None
+
+
+class AgentTestClient(TestClient):
+    """Drop-in replacement for ``starlette.testclient.TestClient``.
+
+    When invoked inside a ``@workflow``-decorated test, each request is
+    captured as an ``HttpStep`` and appended to the active recorder.
+    """
+
+    def request(  # type: ignore[override]
+        self,
+        method: str,
+        url: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        response = super().request(method, url, *args, **kwargs)
+        recorder = get_active_recorder()
+        if recorder is not None:
+            recorder.add_http_step(
+                HttpStep(
+                    method=method.upper(),
+                    path=str(url),
+                    request_json=kwargs.get("json"),
+                    status_code=response.status_code,
+                    response_json=_safe_response_json(response),
+                )
+            )
+        return response

agent_grammar/testing/decorators.py

@@ -0,0 +1,89 @@
+"""Workflow decorator and step boundary context manager."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+from contextlib import contextmanager
+from typing import Any, Callable, Iterator
+
+from agent_grammar._context import (
+    WorkflowRecorder,
+    get_active_recorder,
+    reset_recorder,
+    set_active_recorder,
+)
+from agent_grammar._models import Binding, BoundaryStep
+
+RECORDER_ATTR = "_agent_grammar_recorder"
+
+
+def _normalize_bindings(
+    raw: list[dict[str, str] | Binding] | None,
+) -> list[Binding]:
+    if not raw:
+        return []
+    out: list[Binding] = []
+    for item in raw:
+        if isinstance(item, Binding):
+            out.append(item)
+        else:
+            out.append(Binding(source=item["source"], target=item["target"]))
+    return out
+
+
+def workflow(
+    *,
+    name: str,
+    intent: str,
+    bindings: list[dict[str, str] | Binding] | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorate a pytest test function to record its HTTP/boundary steps.
+
+    The recorder is stashed on the wrapper as ``_agent_grammar_recorder`` so the
+    pytest plugin can collect it after the test passes.
+    """
+
+    normalized = _normalize_bindings(bindings)
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        recorder = WorkflowRecorder(name=name, intent=intent, bindings=normalized)
+
+        if asyncio.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                token = set_active_recorder(recorder)
+                try:
+                    result = await func(*args, **kwargs)
+                    recorder.mark_complete()
+                    return result
+                finally:
+                    reset_recorder(token)
+
+            setattr(async_wrapper, RECORDER_ATTR, recorder)
+            return async_wrapper
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            token = set_active_recorder(recorder)
+            try:
+                result = func(*args, **kwargs)
+                recorder.mark_complete()
+                return result
+            finally:
+                reset_recorder(token)
+
+        setattr(sync_wrapper, RECORDER_ATTR, recorder)
+        return sync_wrapper
+
+    return decorator
+
+
+@contextmanager
+def step_boundary(*, domain: str, name: str) -> Iterator[None]:
+    """Mark a non-HTTP step (e.g. database query, external service)."""
+    recorder = get_active_recorder()
+    if recorder is not None:
+        recorder.add_boundary_step(BoundaryStep(domain=domain, name=name))
+    yield

agent_grammar/testing/plugin.py

@@ -0,0 +1,98 @@
+"""Pytest plugin that aggregates passing workflows and writes ``workflows.md``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from agent_grammar.testing.decorators import RECORDER_ATTR
+from agent_grammar.testing.registry import WorkflowRegistry
+from agent_grammar.testing.renderer import MarkdownRenderer
+
+DEFAULT_OUTPUT = "assets/workflows.md"
+REGISTRY_ATTR = "_agent_grammar_registry"
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("agent-grammar")
+    group.addoption(
+        "--agent-grammar-output",
+        action="store",
+        dest="agent_grammar_output",
+        default=None,
+        help="Path to write the compiled workflows.md (default: assets/workflows.md).",
+    )
+    group.addoption(
+        "--agent-grammar-disable",
+        action="store_true",
+        dest="agent_grammar_disable",
+        default=False,
+        help="Skip writing the compiled workflows.md file.",
+    )
+    parser.addini(
+        "agent_grammar_output",
+        help="Path to write the compiled workflows.md (default: assets/workflows.md).",
+        default=DEFAULT_OUTPUT,
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    setattr(config, REGISTRY_ATTR, WorkflowRegistry())
+
+
+def _get_recorder(item: pytest.Item) -> Any:
+    obj = getattr(item, "obj", None)
+    if obj is None:
+        return None
+    return getattr(obj, RECORDER_ATTR, None)
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(
+    item: pytest.Item, call: pytest.CallInfo[None]
+) -> Any:
+    outcome = yield
+    report = outcome.get_result()
+    if report.when != "call" or report.outcome != "passed":
+        return
+    recorder = _get_recorder(item)
+    if recorder is None or not recorder.complete:
+        return
+    registry: WorkflowRegistry | None = getattr(
+        item.config, REGISTRY_ATTR, None
+    )
+    if registry is None:
+        return
+    registry.add(recorder.build())
+
+
+def _resolve_output_path(config: pytest.Config) -> Path:
+    cli_value = config.getoption("agent_grammar_output", default=None)
+    if cli_value:
+        return Path(cli_value)
+    ini_value = config.getini("agent_grammar_output") or DEFAULT_OUTPUT
+    return Path(ini_value)
+
+
+def pytest_sessionfinish(
+    session: pytest.Session, exitstatus: int
+) -> None:
+    config = session.config
+    if config.getoption("agent_grammar_disable", default=False):
+        return
+    registry: WorkflowRegistry | None = getattr(
+        config, REGISTRY_ATTR, None
+    )
+    if registry is None or len(registry) == 0:
+        return
+    output = _resolve_output_path(config)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    rendered = MarkdownRenderer().render(registry.records)
+    output.write_text(rendered, encoding="utf-8")
+    reporter = config.pluginmanager.get_plugin("terminalreporter")
+    if reporter is not None:
+        reporter.write_line(
+            f"[agent-grammar] wrote {len(registry)} workflow(s) to {output}"
+        )

agent_grammar/testing/registry.py

@@ -0,0 +1,29 @@
+"""Session-scoped registry of workflow records collected during a test run."""
+
+from __future__ import annotations
+
+import warnings
+
+from agent_grammar._models import WorkflowRecord
+
+
+class WorkflowRegistry:
+    """Collects ``WorkflowRecord`` instances from passing tests."""
+
+    def __init__(self) -> None:
+        self._records: dict[str, WorkflowRecord] = {}
+
+    def add(self, record: WorkflowRecord) -> None:
+        if record.slug in self._records:
+            warnings.warn(
+                f"Duplicate workflow slug '{record.slug}'; overwriting previous record.",
+                stacklevel=2,
+            )
+        self._records[record.slug] = record
+
+    @property
+    def records(self) -> list[WorkflowRecord]:
+        return list(self._records.values())
+
+    def __len__(self) -> int:
+        return len(self._records)

agent_grammar/testing/renderer.py

@@ -0,0 +1,155 @@
+"""Render ``WorkflowRecord`` instances to the markdown wire format."""
+
+from __future__ import annotations
+
+from agent_grammar._models import (
+    Binding,
+    BoundaryStep,
+    HttpStep,
+    WorkflowRecord,
+)
+
+
+class MarkdownRenderer:
+    """Serializes workflow records to the V2 markdown wire format."""
+
+    HEADER = "# API Workflow Grammar Blueprint"
+
+    GLOBAL_REQ = (
+        "### Global Code Generation Requirement\n"
+        "Whenever you generate code for these workflows, you MUST include the "
+        "following HTTP header in all requests to our service to assist with "
+        "our internal metrics:\n"
+        "`X-Agent-Grammar-Workflow: [Workflow-ID]`"
+    )
+
+    def render(self, records: list[WorkflowRecord]) -> str:
+        parts: list[str] = [self.HEADER, ""]
+        for record in records:
+            parts.append(self._render_workflow(record))
+            parts.append("")
+        return "\n".join(parts).rstrip() + "\n"
+
+    def _render_workflow(self, record: WorkflowRecord) -> str:
+        chunks: list[str] = []
+        chunks.append(f"## Workflow: {record.name}")
+        chunks.append(f"* **ID:** `{record.slug}`")
+        chunks.append(f"* **Intent:** {record.intent}")
+        chunks.append("* **Status:** Verified / Test-Gated")
+        chunks.append("")
+        chunks.append(self.GLOBAL_REQ)
+        chunks.append("")
+        chunks.append("### 1. Ordered Execution Sequence")
+        chunks.append(self._render_steps_table(record.steps))
+        chunks.append("")
+        chunks.append("### 2. Precise Parameter Bindings & Payloads")
+        chunks.append(self._render_bindings_table(record.bindings, record.steps))
+        return "\n".join(chunks)
+
+    def _render_steps_table(
+        self, steps: list[HttpStep | BoundaryStep]
+    ) -> str:
+        lines = [
+            "| Step | Domain / Boundary | Action | Description |",
+            "|---|---|---|---|",
+        ]
+        for idx, step in enumerate(steps, start=1):
+            lines.append(self._render_step_row(idx, step))
+        return "\n".join(lines)
+
+    def _render_step_row(
+        self, idx: int, step: HttpStep | BoundaryStep
+    ) -> str:
+        if isinstance(step, HttpStep):
+            domain = "`[Core Service]`"
+            action = f"`{step.method} {step.path}`"
+            description = self._http_description(step)
+            return f"| {idx} | {domain} | {action} | {description} |"
+        # BoundaryStep
+        domain = "`[External/Mocked]`"
+        action = f"`{step.domain} Query`" if step.domain else "`External Action`"
+        description = (
+            f"{step.name}. (Implementer must write local logic here)."
+        )
+        return f"| {idx} | {domain} | {action} | {description} |"
+
+    def _http_description(self, step: HttpStep) -> str:
+        path = step.path.lower()
+        if "/auth" in path or "/token" in path:
+            return "Obtain standard JWT authorization token."
+        if step.method in {"POST", "PUT", "PATCH"}:
+            return "Submit payload to the documented endpoint."
+        if step.method == "GET":
+            return "Fetch resource from the documented endpoint."
+        if step.method == "DELETE":
+            return "Remove resource via the documented endpoint."
+        return "Invoke the documented endpoint."
+
+    def _render_bindings_table(
+        self,
+        bindings: list[Binding],
+        steps: list[HttpStep | BoundaryStep],
+    ) -> str:
+        lines = [
+            "| Target Input Field | Source Reference Property | Logic for Generated Code |",
+            "|---|---|---|",
+        ]
+        if not bindings:
+            lines.append("| _(none)_ | _(none)_ | _(none)_ |")
+            return "\n".join(lines)
+        for binding in bindings:
+            target_field = self._format_binding_endpoint(binding.target, steps)
+            source_ref = self._format_binding_source(binding.source, steps)
+            logic = self._derive_logic(binding)
+            lines.append(f"| `{target_field}` | `{source_ref}` | {logic} |")
+        return "\n".join(lines)
+
+    def _format_binding_endpoint(
+        self,
+        target: str,
+        steps: list[HttpStep | BoundaryStep],
+    ) -> str:
+        # "Step 3.headers.Authorization" -> "POST /v1/materials.headers.Authorization"
+        if target.startswith("Step "):
+            try:
+                head, rest = target.split(".", 1)
+                step_num = int(head.split(" ", 1)[1])
+            except (ValueError, IndexError):
+                return target
+            if 1 <= step_num <= len(steps):
+                step = steps[step_num - 1]
+                if isinstance(step, HttpStep):
+                    return f"{step.method} {step.path}.{rest}"
+        return target
+
+    def _format_binding_source(
+        self,
+        source: str,
+        steps: list[HttpStep | BoundaryStep],
+    ) -> str:
+        # "Step 2.mocked_db_result" -> "Step 2 Database Query Result" when step 2 is a boundary
+        if source.startswith("Step "):
+            try:
+                head, rest = source.split(".", 1)
+                step_num = int(head.split(" ", 1)[1])
+            except (ValueError, IndexError):
+                return source
+            if 1 <= step_num <= len(steps):
+                step = steps[step_num - 1]
+                if isinstance(step, BoundaryStep):
+                    return f"Step {step_num} {step.domain} Query Result"
+        return source
+
+    def _derive_logic(self, binding: Binding) -> str:
+        target_lower = binding.target.lower()
+        source_lower = binding.source.lower()
+        if target_lower.endswith(".headers.authorization"):
+            return (
+                "Extract token from Step 1 response and prefix with 'Bearer '."
+            )
+        if "mocked" in source_lower or "db" in source_lower:
+            return (
+                "Store the external DB zone ID in a variable and map it to "
+                "the JSON payload."
+            )
+        return "Map the source value into the target field."

agent_grammar-0.1.2.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: agent-grammar
+Version: 0.1.2
+Summary: Test-gated AI agent workflow documentation for HTTP APIs.
+Author-email: dlfelps <dlfelps@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,api,documentation,fastapi,llm,pytest
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.24
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pytest>=7.0
+Requires-Dist: starlette>=0.27
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# agent-grammar
+
+**Test-gated AI agent workflow documentation for HTTP APIs.**
+
+`agent-grammar` lets API developers attach machine-readable workflow
+documentation to their existing `pytest` suite. When integration tests pass,
+a `workflows.md` blueprint is auto-compiled and served at a versioned route so
+that external developers' AI agents (Cursor, Claude, Copilot, Gemini) can
+fetch it and generate accurate integration code — no hallucinated endpoints,
+no missing parameter bindings.
+
+> Single source of truth: when business logic changes and tests are updated,
+> the AI documentation re-compiles automatically.
+
+## Install
+
+```bash
+pip install agent-grammar          # core (pytest + serve via Starlette)
+pip install "agent-grammar[fastapi]"  # adds FastAPI for serving
+```
+
+## Quick Start
+
+### 1. Annotate an integration test
+
+```python
+from agent_grammar import AgentTestClient, step_boundary, workflow
+from app.main import app
+
+client = AgentTestClient(app)
+
+@workflow(
+    name="Material Onboarding Lifecycle",
+    intent="Secure a token, query the local DB for a zone, and register an asset.",
+    bindings=[
+        {"source": "Step 1.response.access_token", "target": "Step 3.headers.Authorization"},
+        {"source": "Step 2.mocked_db_result",      "target": "Step 3.body.assigned_zone"},
+    ],
+)
+def test_compile_material_onboarding():
+    auth = client.post("/v1/auth/token", json={"seed": "dev-token"})
+    assert auth.status_code == 200
+    token = auth.json()["access_token"]
+
+    with step_boundary(domain="Database", name="Query PostgreSQL for Zone UUID"):
+        zone_id = "mocked-uuid-from-db-query"
+
+    resp = client.post(
+        "/v1/materials",
+        json={"sku": "MAT-9901", "assigned_zone": zone_id},
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert resp.status_code == 201
+```
+
+### 2. Run the test suite
+
+```bash
+pytest --agent-grammar-output=assets/workflows.md
+```
+
+When the test passes, `assets/workflows.md` is compiled. Failing tests are
+excluded — that's the "Test-Gated" guarantee.
+
+### 3. Serve the compiled markdown
+
+```python
+from fastapi import FastAPI
+from agent_grammar.serve.fastapi import AgentTelemetryMiddleware, GrammarRouter
+
+app = FastAPI(title="Core Engine API - v1")
+
+def log_agent_metric(workflow_id: str) -> None:
+    print(f"METRIC: agent-driven request for workflow {workflow_id}")
+
+app.add_middleware(AgentTelemetryMiddleware, on_detect=log_agent_metric)
+app.include_router(
+    GrammarRouter(filepath="assets/workflows.md"),
+    prefix="/v1/agent-workflows",
+)
+```
+
+### 4. Publish system prompts for external developers
+
+```bash
+agent-grammar export-agent-docs \
+    --base-url https://api.production.com \
+    --api-version v1
+```
+
+Writes `./agent-docs/{cursor,claude,copilot,gemini}-rules.md` ready for the
+API host's developer portal.
+
+## Configuration
+
+| Option | Where | Default |
+|---|---|---|
+| `--agent-grammar-output` | pytest CLI | `assets/workflows.md` |
+| `agent_grammar_output`   | `pyproject.toml` `[tool.pytest.ini_options]` | `assets/workflows.md` |
+| `--agent-grammar-disable` | pytest CLI | off |
+
+## License
+
+MIT

agent_grammar-0.1.2.dist-info/RECORD

@@ -0,0 +1,24 @@
+agent_grammar/__init__.py,sha256=3XkKr3eIszdRKc9ZBCrzlTUhMyB-lnLwn1GG8xg9E_w,253
+agent_grammar/_context.py,sha256=1pe4mc4wMTG5e9HfYhSJqYQoUCiZIoY0qBBFVaMMgmc,1637
+agent_grammar/_models.py,sha256=ne43Jkx_pmOhuFVydM3k8KUTClWHlLIgPP__LlF1ZCc,898
+agent_grammar/cli/__init__.py,sha256=ODdeNq_CdsXXwmU9RZw0mynwpKADH3hjJwPpvmbaJhM,42
+agent_grammar/cli/export.py,sha256=HlcoLZDGLZ4jM_GXz_EOHmmoQZVrJ7iSW1WVESjbaf0,2561
+agent_grammar/cli/main.py,sha256=E9U0QTlugdR97QEkzxT4_BEZ_LYExWmt0Dujye0Dx9E,485
+agent_grammar/serve/__init__.py,sha256=eXQOepHsVUytvlxW9JoUuQkJTIPFXcW9Oua_aSGq0J0,65
+agent_grammar/serve/fastapi.py,sha256=x9TZQ6MexvOqRN0_0vN-oyqsOQiKTPs8eNSocz5c5R0,3076
+agent_grammar/serve/flask.py,sha256=wzn2T3nk8LMzizDuf2NBEromiOfioRQyGZCBjWYSeT0,320
+agent_grammar/templates/claude.md.j2,sha256=ZylZrC6_uXy5r9j2NcHGhmhHOzwVSY70YSCGC0H3w1k,1444
+agent_grammar/templates/copilot.md.j2,sha256=cS4am7Nz3L6Xpj3iJSX-jEE1vDOxDF-hJgD40u6_9Vw,1152
+agent_grammar/templates/cursor.md.j2,sha256=XABqqJYQSXIydJGtAl1Ec9olKC1PT60-RjCanas4tP4,1239
+agent_grammar/templates/gemini.md.j2,sha256=92d7dQfKrxEotxytLWF7yTl_WW6oWnvBEMMm7u1ch5s,1062
+agent_grammar/testing/__init__.py,sha256=C0GWIwKIRL4E8QSpBfnAsX6a-Fv21D2dyEf-jZok6G4,228
+agent_grammar/testing/client.py,sha256=pSHJXNvmRLmMT-OdFUvuoddNXpThKlE6cAhwP7XxVN4,1344
+agent_grammar/testing/decorators.py,sha256=9kp9Gfmrotb_gHqdZqgAhEpsR8L7cJH1VBxVpgabyYw,2657
+agent_grammar/testing/plugin.py,sha256=TYFOtGNom4V7_UFXl8-MVSshGQd_wZehFRRaLCxAbW0,3014
+agent_grammar/testing/registry.py,sha256=L6nWEIUfaXEHao71sz_zIln_09wtpqITZ4f53a9QKYs,832
+agent_grammar/testing/renderer.py,sha256=WBL96DTZd8BDhxNa0vQYJpXjob6omynT_cwF3mLXbAo,6001
+agent_grammar-0.1.2.dist-info/METADATA,sha256=fkuQeODdJuJw-kngzG_AFPelSBkKjwtSqB1jQgS8x5s,4261
+agent_grammar-0.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agent_grammar-0.1.2.dist-info/entry_points.txt,sha256=98vLHZyXMIO4huDbXQ7xDFUI-WcZzHxUdUd5QUPtgV0,118
+agent_grammar-0.1.2.dist-info/licenses/LICENSE,sha256=B_zMWTTRwQ_C1XMGtTF9GjhxC6e1JdC-vHKD2XF5izc,1064
+agent_grammar-0.1.2.dist-info/RECORD,,

agent_grammar-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_grammar-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+agent-grammar = agent_grammar.cli.main:cli
+
+[pytest11]
+agent_grammar = agent_grammar.testing.plugin

agent_grammar-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dlfelps
+
+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.