# GrantFlow

> Agent-native grant workflow API for governed proposal operations.

GrantFlow is an HTTP API and MCP tool server that AI agents use to run governed grant proposal workflows: preflight checks, deterministic generation, human-in-the-loop review, quality inspection, and export-ready evidence packs. It is not a chatbot or a CRM.

## Quickstart for agents

- Discover: `GET /.well-known/agent-capabilities.json`
- Tool manifest: `GET /.well-known/agent-tools.json`
- Recipes: `GET /.well-known/agent-recipes.json`
- Live demo (no auth): `GET /demo/run`
- Register sandbox identity: `POST /agents/register`
- Onboard (api_key or oauth_client_credentials): `POST /agents/onboarding`
- Token exchange: `POST /agents/oauth/token`
- Credential introspect: `POST /agents/introspect`

## Core workflow

1. `POST /agents/onboarding` — get API key or OAuth client
2. `POST /ingest/text` — load reference documents (requires ingest:write scope)
3. `POST /ingest/readiness` — confirm corpus coverage
4. `POST /generate/preflight` — check donor readiness before generation
5. `POST /generate` — start a job (returns job_id, poll or use webhook)
6. `GET /status/{job_id}` — poll until done or pending_hitl
7. `POST /hitl/approve` — unblock pending_hitl with approved=true
8. `GET /status/{job_id}/quality` — trust_summary, grounding, critic verdict
9. `GET /status/{job_id}/export-payload` — structured pre-export data
10. `POST /agents/credentials/revoke` — revoke session after work

## Tenant and usage

- Register tenant: `POST /tenants`
- List tenants: `GET /tenants`
- Tenant detail + usage: `GET /tenants/{tenant_id}`
- Usage only: `GET /tenants/{tenant_id}/usage`

## Authentication

Send `X-API-Key: <key>` or `Authorization: Bearer <token>` on protected endpoints.
Auth is optional in sandbox mode. Set `GRANTFLOW_API_KEY` on the server to enforce it.

## Error contract

All errors: `{"detail": {"code": "...", "message": "...", "retryable": bool, "next_action": "..."}}`
`retryable: true` = safe to retry after a wait. `retryable: false` = fix the request first.

## MCP tools

Run: `python -m grantflow.mcp.server`
Key tools: grantflow_onboard_agent, grantflow_ingest_text, grantflow_run_preflight,
grantflow_start_generation, grantflow_get_status, grantflow_hitl_approve,
grantflow_get_quality, grantflow_get_export_payload, grantflow_run_sandbox_happy_path

## Supported donors

Named strategies: usaid, eu, worldbank, giz, state_department, fcdo, afd, jica, adb
All other donors (40+) use GenericDonorStrategy with a shared results framework.

## Portfolio context

GrantFlow is the operational-infrastructure layer in a four-repo AI-native portfolio:
- Reasoning skills: https://github.com/vassiliylakhonin/global-think-tank-analyst (horizontal), https://github.com/vassiliylakhonin/gulf-middle-east-hybrid-intelligence-skill (vertical), https://github.com/vassiliylakhonin/central-asia-caspian-hybrid-intelligence-skill (vertical)
- Evidence / audit layer: https://github.com/vassiliylakhonin/agenda-intelligence-md
- Portfolio site: https://vassiliylakhonin.github.io

## Source and docs

- AGENTS.md — canonical agent integration guide
- docs/agents/quickstart.md — human quickstart
- docs/agents/mcp.md — MCP tool server setup
- docs/agents/error-contract.md — all error codes
- docs/agents/trust-report.md — what GrantFlow verifies vs. operator responsibility
