feat: upgrade runtime recipes

.env.example

@@ -4,11 +4,13 @@ OPENAI_API_KEY=
 # Optional: Custom LLM endpoint (defaults to OpenAI)
 # OPENAI_BASE_URL=https://api.openai.com/v1
 
-# Optional: Model to use (default: gpt-5.2)
-# API_AGENT_MODEL_NAME=gpt-5.2
+# Optional: App config path (defaults to api-agent.toml locally)
+# API_AGENT_CONFIG=api-agent.toml
 
-# Optional: Server port (default: 3000)
-# API_AGENT_PORT=3000
+# Optional: Server port override (defaults to [server].port in api-agent.toml)
+# PORT=3000
+
+# App settings like model live in api-agent.toml.
 
 # Optional: OpenTelemetry tracing endpoint
 # OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

.github/workflows/test.yml

@@ -29,15 +29,21 @@ jobs:
       - name: Install dependencies
         run: uv sync --group dev
 
-      - name: Run tests
-        run: uv run pytest tests/ -v
+      - name: Check lockfile
+        run: uv lock --check
 
       - name: Run linter
-        run: uv run ruff check api_agent/
+        run: uv run ruff check api_agent/ tests/
+
+      - name: Check formatting
+        run: uv run ruff format --check api_agent/ tests/
 
       - name: Run type checker
         run: uv run ty check
 
+      - name: Run tests
+        run: uv run pytest tests/ -q
+
   docker-build:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -18,6 +18,7 @@ wheels/
 .vscode/
 .cursor/
 .claude/
+.codex/
 *.swp
 
 # Testing/Caching

AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.md
+
+Universal agent guidance for this repo.
+
+## Why
+
+`api-agent` turns one GraphQL endpoint or REST OpenAPI spec into an MCP server. Users ask natural-language questions; the server introspects schema, calls the target API, stores tabular data in DuckDB, and runs SQL post-processing when the API cannot filter, rank, join, or aggregate directly.
+
+## What
+
+- `api_agent/__main__.py`: ASGI app, `/mcp`, `/health`
+- `api_agent/config.py`: TOML-only app settings; `API_AGENT_CONFIG` selects file path
+- `api_agent/context.py`: MCP request headers -> `RequestContext`
+- `api_agent/tools/query.py`: public `{prefix}_query` tool
+- `api_agent/agent/`: OpenAI Agents SDK GraphQL/REST flows
+- `api_agent/rest/schema_loader.py`: OpenAPI 3.x + Swagger 2.0 schema loading
+- `api_agent/rest/polling.py`: REST async polling tool
+- `api_agent/recipe/`: learned recipe extraction, storage, matching, tool exposure
+- `api_agent/query_response.py`: wrapped vs direct CSV response formatting
+- `api_agent/executor.py`: DuckDB SQL execution and result shaping
+- `tests/`: pytest coverage by module and behavior
+
+## How
+
+Use deterministic tools first.
+
+```bash
+uv sync --group dev
+uv run pytest tests/ -v
+uv run pytest tests/test_foo.py::test_bar -v
+uv run ruff check api_agent/ tests/
+uv run ruff format --check api_agent/ tests/
+uv run ruff format api_agent/ tests/
+uv run ty check
+```
+
+Before pushing, run the CI lint shape:
+
+```bash
+uv sync --group dev && uv run ruff check api_agent/ && uv run ty check && uv run pytest tests/ -q
+```
+
+Run local server:
+
+```bash
+uv run api-agent
+# public: http://localhost:3000/mcp
+```
+
+Run local server with tracing/debug:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+  uv run --no-sync opentelemetry-instrument api-agent
+```
+
+`start.sh` uses `opentelemetry-instrument` when an OTEL endpoint is set. Do not manually wire OpenAI Agents SDK trace exporters in app code; `openai_agents` auto-instrumentation should load `OpenAIAgentsInstrumentor`.
+
+Useful local override:
+
+```bash
+API_AGENT_CONFIG=api-agent.toml
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```
+
+Put app levers in `api-agent.toml`. Keep `OPENAI_API_KEY` env-only. `OPENAI_BASE_URL` may be TOML or env override. Do not add other app env overrides.
+
+## Rules
+
+- Keep changes testable: functional core, imperative shell.
+- Prefer existing patterns; read nearby code before editing.
+- Update README/docs when behavior, config, deploy, or public tools change.
+- Keep root guidance short; put task-specific detail in README or focused docs.
+- Do not hand-roll formatting/lint checks; run `ruff`/`ty`.
+- For runtime/debug, verify actual TOML path and HTTP behavior.
+- For plans, end with unresolved questions, very concise.
+- Be extremely concise in chat and commit messages.
+
+## Project Facts
+
+- Requests require `X-Target-URL` and `X-API-Type`.
+- `X-API-Name` overrides tool prefix; explicit hyphens preserved.
+- Public MCP exposes `{prefix}_query` plus learned `r_{slug}` tools.
+- `_execute` is removed; query + recipe tools are the public surface.
+- `X-Recipe-Learn-Rate: 1` forces successful-query recipe extraction.
+- Recipe params are required top-level fields; examples are hints, not defaults.
+- Unsafe REST writes are blocked unless allowed by `X-Allow-Unsafe-Paths`.

CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+This file tracks notable service changes. It is not tied to package publishing,
+GitHub Releases, or tag-based deployment.
+
+## Current
+
+### Added
+
+- Add generated downstream API descriptions with storage-backed caching.
+- Add shared memory/Redis storage for recipes and generated descriptions.
+- Add configurable description model and timeout.
+
+### Changed
+
+- Upgrade query and recipe runtime flow around shared GraphQL/REST execution.
+- Move app configuration into `api-agent.toml`.
+- Make recipe tools return CSV directly.
+- Change learned recipe storage to the `public_contract` and `execution_plan`
+  format. Older learned recipes are not migrated automatically and should be
+  cleared, migrated, or relearned.
+- Split recipe contracts, execution, extraction models, prompts, and tooling into
+  focused modules.
+
+### Removed
+
+- Remove the legacy `_execute` public tool surface.
+
+## OpenAPI compatibility - 2026-03-05
+
+### Added
+
+- Add Swagger 2.0 schema loading.
+- Add structured HTTP error details.
+
+## Documentation update - 2026-02-23
+
+### Changed
+
+- Clarify unsafe REST path and polling header escaping examples.
+
+## Recipe tools - 2026-02-07
+
+### Added
+
+- Add direct `r_{slug}` recipe tools.
+- Add recipe execution for cached GraphQL and REST workflows.
+- Add CSV response helpers for direct recipe output.
+
+## Recipe learning - 2026-01-27
+
+### Added
+
+- Add learned recipe extraction, caching, and matching.
+- Add recipe-aware query flow and recipe store tests.
+
+## Initial baseline - 2026-01-12
+
+### Added
+
+- Initial release of API Agent as an MCP server for natural-language API queries.
+- Add GraphQL and REST schema loading, request execution, and DuckDB SQL
+  post-processing.
+- Add `{prefix}_query` tool with configurable target API headers.
+- Add Docker, CI, README, CONTRIBUTING, and test coverage.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md