git:20260906.e62b9e9 to git:20260906.a82d4dd

# GNN API Module — Agent Scaffolding

## Module Overview

**Purpose**: FastAPI-based REST interface for programmatic pipeline invocation, job management, and tool discovery.

**Pipeline Step**: Infrastructure module (not a numbered step)

**Category**: Infrastructure / API

**Status**: Production Ready

**Version**: 3.2.0

**Last Updated**: 2026-04-16

The `api` module provides a FastAPI-based REST interface for the GNN processing pipeline.

It enables programmatic pipeline invocation, job management, and tool discovery without

requiring direct CLI access.

## Architecture

```

src/gnn/api/

__init__.py -- Module metadata, availability checks

app.py -- FastAPI "run" surface (run/runs/report/stream/health); `gnn serve` entry point

server.py -- FastAPI "job/tool" surface (process/jobs/tools/health)

models.py -- Pydantic request/response models (API contract)

responses.py -- Canonical envelopes and exception handlers

processor.py -- In-memory job manager (create_job/get_job/cancel_job/list_jobs/get_pipeline_tools)

auth.py -- Optional API-key authentication (GNN_API_KEY)

path_utils.py -- Symlink-safe repo path resolution

rate_limit.py -- Request rate limiting

mcp.py -- MCP tool registration manifest

AGENTS.md -- This file

```

## Endpoints

| Method | Path | Description |

|--------|------|-------------|

| POST | /api/v1/process | Submit pipeline job |

| GET | /api/v1/jobs/{id} | Poll job status |

| DELETE | /api/v1/jobs/{id} | Cancel job |

| GET | /api/v1/jobs | List recent jobs |

| GET | /api/v1/tools | List pipeline steps |

| POST | /api/v1/tools/{step} | Invoke single step |

| GET | /api/v1/health | Health check |

The module exposes two independent FastAPI apps. The table above is the

`api.server` job/tool surface; `api.app` (started by `gnn serve`) exposes

`POST /api/v1/run`, `GET /api/v1/runs`, `GET /api/v1/runs/{hash}`,

`GET /api/v1/runs/{hash}/report` (Markdown), `GET /api/v1/runs/{hash}/stream`

## Installation

The API module requires optional dependencies:

```bash

uv sync --extra api

# then:

# or:

```

## Design Decisions

- **Optional API-key authentication** (`api/auth.py`): unauthenticated for

loopback research use by default; set `GNN_API_KEY` to require a matching

`X-API-Key` header on every route outside the public health/docs surface

(constant-time `hmac.compare_digest`). Non-loopback binds are refused unless

auth is enabled or `GNN_ALLOW_INSECURE_BIND=1` (RED_TEAM V-04).

- **In-memory jobs**: No database required. Jobs lost on restart.

- **AsyncIO execution**: Non-blocking pipeline runs via asyncio subprocess.

- **Background tasks**: FastAPI BackgroundTasks for fire-and-forget job execution.

- **CORS**: Allows localhost origins for browser-based access.

- **Symlink-safe path validation**: `path_utils.resolve_repo_path` rejects any

symlink component before resolving (RED_TEAM V-05).

- **Sanitized error responses**: job failure tails redact the repository root

and absolute paths before returning to callers (RED_TEAM V-09).

- **Canonical JSON envelope**: successful and failed JSON responses use exactly

`{status, data, error, meta}`. Validation, HTTP, authentication, rate-limit,

and unexpected exceptions pass through the same contract. The Markdown

report download remains `text/markdown`; SSE event payloads use the envelope.

## Integration with Pipeline

This module is NOT a numbered pipeline step. It is an optional service module

that wraps the pipeline for API access. Import it independently:

```python

from gnn.api.processor import create_job, get_job, cancel_job, list_jobs, get_pipeline_tools

```

## Agent Guidance

When working with this module:

1. The `processor.py` contains job lifecycle logic -- extend it for persistence needs

2. The `models.py` is the API contract -- update schemas and tests together

3. Add new endpoints in `server.py` (job/tool surface) or `app.py` (run/runs surface) following the canonical envelope pattern

---

## Documentation

- **[README](README.md)**: Module Overview

- **[AGENTS](AGENTS.md)**: Agentic Workflows

- **[SPEC](SPEC.md)**: Architectural Specification

- **[SKILL](SKILL.md)**: Capability API