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
