agent-grammar 0.1.2__tar.gz

agent_grammar-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install package with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-grammar
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_grammar-0.1.2/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+.venv/
+venv/
+.env
+*.swp
+.DS_Store

agent_grammar-0.1.2/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.

agent_grammar-0.1.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,104 @@
+# 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/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-grammar"
+dynamic = ["version"]
+description = "Test-gated AI agent workflow documentation for HTTP APIs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "dlfelps", email = "dlfelps@gmail.com" }]
+keywords = ["pytest", "ai", "agents", "llm", "api", "documentation", "fastapi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "pytest>=7.0",
+    "starlette>=0.27",
+    "httpx>=0.24",
+    "jinja2>=3.1",
+    "click>=8.1",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+dev = [
+    "fastapi>=0.100",
+    "pytest-cov",
+    "mypy",
+    "ruff",
+]
+
+
+
+[project.entry-points.pytest11]
+agent_grammar = "agent_grammar.testing.plugin"
+
+[project.scripts]
+agent-grammar = "agent_grammar.cli.main:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_grammar"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.version]
+path = "src/agent_grammar/__init__.py"

agent_grammar-0.1.2/src/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-0.1.2/src/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-0.1.2/src/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-0.1.2/src/agent_grammar/cli/__init__.py

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

agent_grammar-0.1.2/src/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-0.1.2/src/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-0.1.2/src/agent_grammar/serve/__init__.py

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