GrantFlow

Agent-native grant workflow infrastructure for governed proposal operations.

GrantFlow gives AI agents and workflow systems a governed API for donor-aware proposal drafting, preflight checks, human review, traceability, and export-ready evidence packs.

It is not a grant-writing chatbot. It is the API layer an agent can discover, register with, call safely, and audit.

Who is this for?

NGO and implementer teams that run recurring EU, USAID, FCDO, AFD, JICA, ADB, or UN grant cycles and want to reduce the manual draft-review loop. GrantFlow handles the governed generation pipeline so your team reviews outputs, not blank pages.

AI agent builders who need a workflow API with auth, idempotency, HITL checkpoints, structured errors, and audit trails — without building that layer themselves.

Not for: one-off grant applications, donor portal automation bots, or anyone who needs a chatbot UI. GrantFlow is infrastructure, not a product your end-users click through.

Try it now

Start the API locally, then hit the demo endpoint — no auth, runs in under 2 seconds:

cp .env.example .env           # set GRANTFLOW_CHEAP_MODEL / GRANTFLOW_REASONING_MODEL if using LLM mode
make bootstrap-dev && source .venv/bin/activate
uvicorn grantflow.api.app:app --reload
# In another terminal:
curl http://127.0.0.1:8000/demo/run | python3 -m json.tool

Expected response shape:

{
  "demo": true,
  "job_id": "demo_...",
  "donor_id": "usaid",
  "status": "done",
  "event_count": 4,
  "quality": {
    "verdict": "conditional",
    "grounding_verified": false,
    "critic_score": 0.0
  },
  "next": {
    "onboard": "POST /agents/onboarding",
    "ingest": "POST /ingest/text",
    "preflight": "POST /generate/preflight",
    "generate": "POST /generate"
  }
}

verdict: conditional in the demo is expected — no corpus was ingested. Load documents via POST /ingest/text and re-run with llm_mode=true for a grounded result.

Machine-readable project description for LLM agents: GET /llms.txt · llms.txt
Sandbox proof-of-life endpoint (no auth): GET /demo/run

Why GrantFlow

The next proposal operator may be an AI agent, not a person clicking through a dashboard. That agent still needs operational controls: discovery, typed contracts, auth, idempotency, preflight gates, review checkpoints, audit events, and deterministic smoke tests.

GrantFlow is built around that contract.

• Agent discovery via /.well-known/agent-capabilities.json
• Agent descriptor via /.well-known/agent.json
• Agent policy via /.well-known/agent-policy.json
• Task-level tool manifest via /.well-known/agent-tools.json
• Use-case recipes via /.well-known/agent-recipes.json
• Sandbox agent registration via POST /agents/register
• Self-serve agent onboarding via POST /agents/onboarding
• OAuth client-credentials token exchange via POST /agents/oauth/token
• Credential introspection via POST /agents/introspect
• Credential rotation and revocation via POST /agents/credentials/rotate and POST /agents/credentials/revoke
• Structured agent errors for auth, idempotency, and generation startup failures
• MCP-style stdio tool server for runtimes that prefer tools/list and tools/call
• Human-in-the-loop checkpoints for controlled pause, approve, reject, and resume
• Traceable status, quality, citation, version, and lifecycle event surfaces
• Exports to .docx, .xlsx, and buyer-facing ZIP evidence packs

Core Workflow

1. Discover capabilities and tools.
2. Onboard credentials or register a sandbox agent identity.
3. Run donor/readiness preflight.
4. Start deterministic generation with an idempotency key.
5. Poll status or consume webhook callbacks.
6. Inspect quality, grounding, citations, and audit events.
7. Export reviewable deliverables and evidence packs.

Agent Quickstart

Start the API:

make bootstrap-dev
source .venv/bin/activate
uvicorn grantflow.api.app:app --reload

Discover the agent contract:

export GRANTFLOW_BASE_URL="http://127.0.0.1:8000"

curl "$GRANTFLOW_BASE_URL/.well-known/agent-capabilities.json"
curl "$GRANTFLOW_BASE_URL/.well-known/agent-tools.json"
curl "$GRANTFLOW_BASE_URL/.well-known/agent-recipes.json"

Request self-serve onboarding:

curl -X POST "$GRANTFLOW_BASE_URL/agents/onboarding" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "proposal-worker",
    "auth_type": "api_key",
    "requested_scopes": ["generate:write", "status:read", "quality:read"]
  }'

Request OAuth client credentials and exchange a Bearer token:

curl -X POST "$GRANTFLOW_BASE_URL/agents/onboarding" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "proposal-worker",
    "auth_type": "oauth_client_credentials",
    "requested_scopes": ["generate:write", "status:read", "quality:read"]
  }'

curl -X POST "$GRANTFLOW_BASE_URL/agents/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$GRANTFLOW_CLIENT_ID"'",
    "client_secret": "'"$GRANTFLOW_CLIENT_SECRET"'",
    "scope": "generate:write status:read quality:read"
  }'

Register a sandbox agent for sample payloads:

curl -X POST "$GRANTFLOW_BASE_URL/agents/register" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "proposal-worker",
    "agent_type": "workflow_agent",
    "purpose": "Run deterministic GrantFlow smoke workflows"
  }'

The response includes sample_requests.preflight and sample_requests.generate, so an agent can immediately run a safe sandbox workflow.

Full guide: docs/agents/quickstart.md

Self-serve agent keys carry expiry, tenant, and scopes. Agent-critical endpoints enforce tenant_id and scopes when API-key auth is active.

Short-lived runtime sessions are available at POST /agents/session.

Agents can validate X-API-Key or Authorization: Bearer credentials with POST /agents/introspect before calling protected tools.

Agents can rotate or revoke self-serve credentials:

curl -X POST "$GRANTFLOW_BASE_URL/agents/credentials/rotate" \
  -H "Content-Type: application/json" \
  -d '{"credential":"'"$GRANTFLOW_AGENT_CREDENTIAL"'","ttl_seconds":3600}'

curl -X POST "$GRANTFLOW_BASE_URL/agents/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d '{"credential":"'"$GRANTFLOW_AGENT_CREDENTIAL"'","reason":"credential rotation completed"}'

Revocation uses an in-process jti denylist for sandbox/controlled deployments. The revoke response includes revocation_scope: "in_process" and restart_safe: false so agents read this limitation without consulting docs. Multi-replica production should enforce revocation at the gateway layer.

Run an external agent conformance smoke:

python -m grantflow.agents.conformance --base-url "$GRANTFLOW_BASE_URL"

MCP-Style Tool Server

For agent runtimes that prefer stdio tools:

export GRANTFLOW_BASE_URL="http://127.0.0.1:8000"
export GRANTFLOW_API_KEY="optional-production-key"
python -m grantflow.mcp.server

Supported tool calls (17 tools):

• grantflow_onboard_agent
• grantflow_create_session
• grantflow_introspect_agent
• grantflow_exchange_oauth_token
• grantflow_rotate_credential
• grantflow_revoke_credential
• grantflow_register_agent
• grantflow_ingest_text
• grantflow_run_preflight
• grantflow_start_generation
• grantflow_get_status
• grantflow_get_quality
• grantflow_get_events
• grantflow_hitl_approve
• grantflow_hitl_list_pending
• grantflow_get_export_payload
• grantflow_run_sandbox_happy_path

Tool server guide: docs/agents/mcp.md

Production MCP transport with the official Python SDK is available as an optional extra:

pip install "grantflow[mcp]"
GRANTFLOW_MCP_TRANSPORT=streamable-http python -m grantflow.mcp.fastmcp_server

Human Review And Governance

GrantFlow keeps agent-driven work inside reviewable boundaries:

• HITL checkpoints for architect, table of contents, MEL, and logframe stages
• Critic findings and review comments with lifecycle status
• SLA and portfolio signals for review operations
• Grounding gates, citation checks, and readiness warnings
• Audit-friendly job events and traceability endpoints

Production Boundaries

• Built-in auth accepts signed self-serve API keys and self-serve OAuth Bearer tokens in controlled deployments.
• Enterprise IAM/OIDC/SAML/RBAC can sit at the gateway/platform layer while reusing GrantFlow's agent onboarding metadata.
• Queue-backed runtime and worker mode are supported.
• Production compose example: docker-compose.production.example.yml
• Customer-specific pilot data stays outside this public repository.

See also:

• docs/production-boundaries.md
• docs/reference-topology.md
• docs/enterprise-access-layer.md
• SECURITY.md

Supported Donors

Each donor has a dedicated strategy class with typed ToC schema, MEL schema, role-specific prompts, and a RAG namespace.

All other donors in the catalog (40+) use GenericDonorStrategy with a shared results framework.

Maturity and pilot offer

No customer pilots yet. The benchmark numbers in docs/pilot_benchmark_assumptions.json are illustrative demo baselines, not measured customer results. See docs/proof-summary.md.

Donor paths most built out today:

• EU
• FCDO
• USAID — conditional, depending on use case and operating constraints

Pilot offer (to produce the first real proof):

• ICP: NGO/implementer teams with recurring EU/FCDO/USAID workflows
• Scope: 3-6 representative cases with named owners
• Exit: Go/No-Go based on cycle-time delta, review-loop delta, and trust in traceability

Canonical pilot path: docs/canonical-pilot-path.md

Trust Report

Before export, the quality surface at GET /status/{job_id}/quality includes a trust_summary block:

{
  "trust_summary": {
    "verdict": "pass" | "conditional" | "fail",
    "grounding_verified": true,
    "open_high_severity_findings": 0,
    "hitl_cleared": true,
    "export_contract_cleared": true,
    "buyer_note": "All quality gates cleared. Proposal is ready for export."
  }
}

Agents and buyers read verdict to decide whether to proceed to export. A conditional or fail verdict means at least one gate is not cleared — check buyer_note for the specific reason.

Full trust report and production boundary breakdown: docs/agents/trust-report.md

Docs Map

• Agents: AGENTS.md, docs/agents/quickstart.md, docs/agents/mcp.md, docs/agents/error-contract.md, docs/agents/trust-report.md, docs/agents/webhook-verification.md
• Buyers: docs/buyer-one-pager.md, docs/pilot-evaluation-checklist.md, docs/proof-summary.md
• Operators: docs/demo-runbook.md, docs/operations-runbook.md, docs/pilot-day1-checklist.md
• Deployment: docs/deployment/oauth-gateway.md, docs/deployment/credential-revocation.md
• Engineers: docs/README.md, docs/architecture.md, docs/contributor-map.md

Development Checks

make qa-fast                                    # ruff + black check + pytest core + mypy
.venv/bin/python scripts/api_contract_guard.py  # API contract guard

Full test suite and linters: see CONTRIBUTING.md → "Local Checks Before Push".

The main branch is expected to stay green across CI, supply-chain checks, demo smoke, HITL smoke, grounded evaluation, and docker-compose smoke.