Metadata-Version: 2.4
Name: agentgraph-api
Version: 0.1.0
Summary: Generic FastAPI service layer for AgentGraph Core.
Author-email: cool <cool@phper.org>
License: MIT
Requires-Python: >=3.11
Requires-Dist: agentgraph-core>=0.1.0
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.27
Provides-Extra: test
Requires-Dist: httpx>=0.27; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# AgentGraph API

AgentGraph API is a generic FastAPI service layer for [`agentgraph-core`](https://github.com/nophp/agentgraph-core).

It is intentionally separate from the core runtime package:

- `agentgraph-core`: UI-free runtime/control-plane primitives.
- `agentgraph-api`: generic HTTP routes, auth hook, JSON serialization, CRUD, and mirror endpoints.
- Applications provide their own adapters, tools, authentication, and product UI.

## Included routes

All generic routes live under:

```text
/api/agentgraph
```

Current v0 routes:

- `GET /summary`
- `GET|POST /agents`
- `GET|POST /graphs`
- `GET|POST /tools`
- `GET|POST /tools/executions`
- `GET /tools/executions/{id}`
- `POST /tools/executions/{id}/decision`
- `GET|POST /runs`
- `POST /runs/import`
- `GET /runs/{id}`
- `GET /runs/{id}/events`
- `GET /runs/{id}/artifacts`
- `GET /human-gates`
- `GET /human-gates/{id}`
- `POST /human-gates/{id}/decision`
- `GET|POST /knowledge`
- `GET /knowledge/{id}`
- `GET /knowledge/{id}/evidence`
- `POST /knowledge/{id}/decision`
- `GET|POST /schedules`
- `GET /schedules/{id}`
- `POST /schedules/{id}/decision`

Health:

- `GET /health`

## Minimal usage

```python
from agentgraph_api import AgentGraphApiContext, create_app
from agentgraph_core.models import ToolDefinition, ToolRisk

context = AgentGraphApiContext.create(
    db_path="data/my-project-agentgraph.sqlite3",
    tools=[ToolDefinition(id="echo", name="Echo", description="Echo input", risk=ToolRisk.read)],
    tool_handlers={"echo": lambda payload: {"echo": payload}},
    project_name="my-project",
)

app = create_app(context, auth_token="dev-token")
```

Run:

```bash
uvicorn agentgraph_api.app:app --host 127.0.0.1 --port 18889
```

## Auth

`create_app(..., auth_token="...")` enables a simple Bearer-token dependency for `/api/agentgraph/*` routes.

Applications can replace this entirely with their own auth layer. AgentGraph API does not own user/session management.

## Application adapter pattern

```text
application UI / service
  -> application adapter
  -> agentgraph-api generic routes
  -> agentgraph-core store + policies
  -> application-specific tools and state authority
```

Use this package when an application wants the standard AgentGraph HTTP surface without copying FastAPI route code into every project.

## Development

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytest -q
python -m compileall agentgraph_api tests
```
