Case Study: GrantFlow

TL;DR

Built GrantFlow — an agent-native grant workflow API for donor-aware proposal operations, governed review, traceability, and export-ready evidence packs.
It is not a grant-writing chatbot. It is the API layer an AI agent can discover, register with, call safely, and audit.
Built around the operational contract a real agent runtime needs: typed .well-known discovery, scoped self-serve credentials, OAuth client-credentials, idempotency keys, deterministic generation, HITL checkpoints, audit events, and .docx / .xlsx / ZIP exports.
Positioned for NGO / implementer teams with recurring EU and UN workflows, and for any agent runtime that needs governed grant operations rather than ad-hoc LLM calls.

Evidence

Public GitHub repository: grantflow
Latest release: v2.3.3 (2026-05-13).
Universal agent contract: AGENTS.md — shortest path for agents to discover, authenticate, and use the API without reading the full repo.
Agent quickstart: docs/agents/quickstart.md.
MCP tool-server guide: docs/agents/mcp.md.
Trust report format: docs/agents/trust-report.md.
Architecture, production boundaries, reference topology, and enterprise access layer documented under docs/.

Project state (self-reported)

Distribution: public Python repository, FastAPI service, container build, MCP stdio server, optional streamable-http MCP transport via pip install "grantflow[mcp]". Python 3.11–3.13 supported.
Implemented surfaces: five .well-known discovery routes (agent-capabilities.json, agent.json, agent-policy.json, agent-tools.json, agent-recipes.json); full credential lifecycle (POST /agents/onboarding, /oauth/token, /introspect, /credentials/rotate, /credentials/revoke); POST /agents/session; tenant management (POST /tenants, GET /tenants, GET /tenants/{tenant_id}, GET /tenants/{tenant_id}/usage) with advisory daily quotas; preflight gates; Redis-backed deterministic generation with idempotency keys; status / quality / grounding / events endpoints; trust_summary block in /quality payload (verdict, grounding_verified, buyer_note); HITL checkpoints; exports; GET /demo/run (no auth required); GET /llms.txt.
MCP tool surface: stdio (grantflow.mcp.server) and optional streamable-http transports; 17 named tools covering the full agent lifecycle — agent onboarding, session, introspection, OAuth token exchange, credential rotation and revocation, sandbox registration, ingest, preflight, generation start, status / quality / events, HITL approve and list-pending, export payload, and a sandbox happy-path runner.
CI: unit tests, mypy (full type-gating restored), ruff, supply-chain checks, demo smoke, HITL smoke, grounded LLM evaluation, docker-compose smoke, nightly grounded tail, synthetic alert delivery check, E2E webhook verification, contract tests for all tenant and quality endpoints.
Donor template coverage: dedicated strategy classes (typed ToC schema, MEL schema, role-specific prompts, RAG namespace) for USAID, EU (INTPA), World Bank / IFC, GIZ, U.S. State Department, FCDO, AFD, JICA, and ADB; EU and FCDO are the strongest paths, USAID conditional. All other donors in the catalog (40+) use GenericDonorStrategy with a shared results framework.
No production-adoption, customer, or benchmark numbers are claimed. Customer-specific pilot data stays outside the public repository by design.

Context / Constraint

The next operator running a grant proposal cycle 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.

A single LLM endpoint with a "draft a proposal" prompt is not a workflow — it is an unbounded text generator without traceability, governance, or export-ready outputs.

Donor reviewers and audit teams need traceable evidence; agent runtimes need stable contracts and bounded retries; NGO operators need human checkpoints and review SLAs. All three have to live in one API.

Problem

Most agent-assisted proposal workflows are wrappers around a chat model. They produce text fluently. They struggle with the operational shape of real grant work: tenanted access, idempotent generation across retries, donor-specific preflight gates, structured review states, audit events, grounding inspection, and exportable evidence packs.

Buyers cannot ship that into an EU or UN review process. Agent runtimes cannot orchestrate it reliably. Operations teams cannot audit it after the fact.

Actions

Reframed the project from "AI proposal assistant" to agent-native grant workflow API. The core artifact is an OpenAPI surface with .well-known discovery, not a chat UI.
Wrote AGENTS.md as the shortest path for AI agents to discover, authenticate, and use GrantFlow without reading the full repo.
Defined the agent operational contract: discovery → onboarding → preflight → deterministic generation with an idempotency key → status / quality / events → HITL review → export.
Implemented self-serve credentials (signed API keys with expiry, tenant, and scopes) and OAuth client-credentials, with full lifecycle: onboarding → token exchange → introspection → rotation → revocation. Agent-critical endpoints enforce tenant_id and scopes when API-key auth is active.
Added multi-tenant infrastructure: POST /tenants, GET /tenants, GET /tenants/{tenant_id}, GET /tenants/{tenant_id}/usage with advisory daily quotas on jobs and ingest.
Added MCP tool surface: stdio and streamable-http transports; 17 named tools spanning onboarding, credentials, ingest, preflight, generation, status / quality / events, HITL, export, and a sandbox happy-path runner.
Added trust_summary block to the /quality payload — verdict, grounding_verified, buyer_note — so a buyer or agent can read the trust state without parsing the full response.
Added GET /demo/run (no auth required, result in ~2 seconds) and GET /llms.txt for machine-readable project description.
Upgraded idempotency to Redis-backed storage so retries hold across restarts, not only in-memory.
Implemented HITL checkpoints (architect, table of contents, MEL, logframe), critic findings, review comments with lifecycle status, SLA and portfolio signals, grounding gates, citation checks, and readiness warnings.
Added structured agent errors for auth, idempotency, and generation startup failures so an agent can branch on them rather than parse free-form messages.
Added exports to .docx, .xlsx, and buyer-facing ZIP evidence packs.
Built CI for supply-chain checks, deterministic smoke, HITL smoke, grounded LLM evaluation, docker-compose smoke, nightly grounded tail, synthetic alert-delivery checks, E2E webhook verification, and contract tests for all tenant and quality endpoints. Restored full mypy type-gating.
Documented production boundaries explicitly: built-in auth covers controlled deployments; enterprise IAM / OIDC / SAML / RBAC sits at the gateway / platform layer and reuses GrantFlow's onboarding metadata. Customer-specific pilot data stays outside the public repository.
Defined a canonical pilot path: 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.

What it does now

Lets an AI agent discover its capabilities, tools, policy, and recipes through five .well-known endpoints before any real call.
Onboards agents with self-serve API keys or OAuth client credentials, in tenanted, scoped, expiring form; rotates and revokes credentials without downtime.
Manages tenants with advisory daily quotas so multi-org deployments stay isolated.
Runs donor-aware preflight gates before a generation starts.
Runs deterministic generation against a Redis-backed idempotency key so retries and reconnects do not duplicate work across restarts.
Surfaces status, quality (including trust_summary with verdict and buyer note), grounding, citations, version, and lifecycle events on stable endpoints.
Pauses at HITL checkpoints and resumes only after explicit approval.
Exports .docx, .xlsx, and ZIP evidence packs that are ready for donor review.
Exposes a demo endpoint (GET /demo/run) with no auth required and a machine-readable llms.txt for agent discovery.
Travels across runtimes: any HTTP-capable agent, plus MCP runtimes via stdio or streamable-http with 17 named tools.

Trust-layer update — 2026-05

GrantFlow's trust-layer differs from the markdown-skill repos in the portfolio: it lives in code and contracts, not just documentation. The buyer-facing trust artifacts are now explicit:

Output trust (docs/agents/trust-report.md) — what trust_summary.verdict (export_ready / needs_review / needs_revision / incomplete) means, what it does not mean, and the recommended agent workflow. Honest limitations are stated: grounded: true reflects the runtime grounding gate, not factual correctness; critic_passed: true means no open high-severity findings, not zero findings; export_ready is a governance signal, not a legal certification.
Error contract (docs/agents/error-contract.md) — structured detail.code / retryable / next_action shape for every agent-facing endpoint; agents branch on machine-readable codes, not on HTTP status or free-form text.
Threat model (docs/agents/threat-model.md, 2026-05) — ten classes of input/processing-side gaps GrantFlow does not catch: prompt-injection in proposal text or RAG content, factual correctness, hallucinated citations that look well-formed, donor template drift, cross-tenant content leakage through shared embeddings, spoofed donor profile, replay within the idempotency window, adversarial inputs at scale, operator misuse of hitl_enabled=false. A passing export_ready verdict means GrantFlow's governance signals all passed — not that the proposal is correct, safe, or submittable without human review.
HITL checkpoints — physical trust-layer, not just declaration: jobs pause at designated stages until a human resolves them when hitl_enabled=true.

What it is not

Not a grant-writing chatbot.
Not a one-click "auto-fill my proposal" tool.
Not a replacement for human review, donor relationship work, or organizational accountability.
Not a database of donor calls, beneficiaries, or pre-approved language.
Not a SaaS product with public customer references in this repository — pilot data stays outside the public repo by design.
Not an enterprise IAM / OIDC / SAML / RBAC implementation in itself — those concerns sit at the gateway / platform layer.

Tech stack

Python (FastAPI) service.
OpenAPI surface with x-grantflow-agent-recipes extension and a dedicated recipes endpoint.
MCP tool servers: stdio (grantflow.mcp.server) and optional streamable-http (grantflow.mcp.fastmcp_server) via pip install "grantflow[mcp]".
Self-serve signed API keys and OAuth client-credentials, with introspection, rotation, and revocation.
Docker / docker-compose, including a pilot compose file and a production-compose example.
Makefile-based bootstrap (make bootstrap-dev).
CI: pytest, mypy, ruff, supply-chain checks, demo smoke, HITL smoke, grounded LLM evaluation, docker-compose smoke, nightly grounded tail, synthetic alert delivery check, release-cut and release-drafter workflows.
Topics on the public repo: fastapi, mcp, agentic-ai, ai-agents, api-first, grant-proposals, grant-management, proposal-workflow, human-in-the-loop, traceability, donor-workflows, nonprofit-tech, workflow-automation, document-generation, openapi.

Companion projects

Agenda Intelligence MD — schemas, validators, and evidence-audit tooling that can score and audit outputs the agent produces through GrantFlow.

Relevance

This project demonstrates how I think about practical infrastructure for agent-driven nonprofit operations: typed contracts before chat UI, governed credentials before "trust the agent", deterministic generation before clever prompting, HITL and audit events before "just ship it", and exports that hold up in front of an EU or UN reviewer.

The honest scope is also part of the design: customer pilot data stays out of the public repository, no production adoption is claimed, and the README's "Maturity and pilot offer" section names current strongest donor-template paths rather than customer references.

Project links

Author: Vassiliy Lakhonin