grantflow

# 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. > **Boundaries.** Not legal, compliance, financial, or grant-eligibility advice. GrantFlow enforces evidence structure and grounding signals — it does not verify the factual truth of any claim and does not retrieve live sources on its own. A human must review before any submission. [](https://github.com/vassiliylakhonin/grantflow/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://www.python.org/) [](https://fastapi.tiangolo.com/) --- ## 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 **Hosted demo (no install).** A deterministic demo runs free on Hugging Face Spaces — no auth, no LLM cost: ```bash # First call can take ~30s (the Space cold-starts when idle); warm calls are sub-second. curl https://vassilbek-grantflow.hf.space/demo/run | python3 -m json.tool curl https://vassilbek-grantflow.hf.space/donors | python3 -m json.tool # donors + per-donor submission_requirements ``` **Run locally** — no auth, runs in under 2 seconds: ```bash 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: ```json { "demo": true, "job_id": "demo_...", "donor_id": "usaid", "status": "done", "event_count": 3, "quality": { "verdict": "needs_revision", "grounding_verified": null, "critic_score": 2.75 }, "next": { "onboard": "POST /agents/onboarding", "ingest": "POST /ingest/text", "preflight": "POST /generate/preflight", "generate": "POST /generate" } } ``` `verdict: needs_revision` in the demo is expected — it is a deterministic sandbox run with no corpus 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) · [`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 ## What a governance pass adds (before → after) GrantFlow does not write a better narrative than a strong general model — it adds the governance layer a general model leaves out. Run an AI-drafted results framework through GrantFlow and the same content comes back with the gaps a donor reviewer would flag, plus the records a funder increasingly asks for. The fields below are illustrative of real output shapes, not a specific organization's proposal. **Before — a typical AI-drafted logframe** - Baselines are assumptions: `35%*`, `~180 min`, `TBD`, `not tracked`. - Targets drift between the logframe and the KPI sheet (e.g. `75%` in one table, `60% (Yr1) / 75% (Yr2)` in another). - No record of how the draft was produced. - Structure is "donor style", not checked against the donor's mandated sections. **After — the same draft through GrantFlow** - **Donor-structure check** — output validated against the donor template; `present_sections` / `missing_required_sections` reported (e.g. U.S. State Dept program logic requires `program_goal`, `objectives`, `Risk Mitigation`). - **Grounding** — each indicator carries a `citation` + `evidence_excerpt` tied to an ingested source, or is surfaced as unsupported. - **Trust verdict** — `export_ready` / `needs_review` / `needs_revision` with explicit `blocking_reasons`, so nothing reaches export on unverified footing. - **AI-use disclosure** — a machine-readable record (`generation_mode`, `models`, grounding signals, `human_review` required) to attach to the submission. What stays human: establishing real baselines, reconciling targets, confirming the live solicitation format. GrantFlow surfaces what is not ready; a person fixes it. ## 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: ```bash make bootstrap-dev source .venv/bin/activate uvicorn grantflow.api.app:app --reload ``` Discover the agent contract: ```bash 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: ```bash 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: ```bash 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: ```bash 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`](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: ```bash 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: ```bash python -m grantflow.agents.conformance --base-url "$GRANTFLOW_BASE_URL" ``` ## MCP-Style Tool Server For agent runtimes that prefer stdio tools: ```bash 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`](docs/agents/mcp.md) Production MCP transport with the official Python SDK is available as an optional extra: ```bash 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`](docker-compose.production.example.yml) - Customer-specific pilot data stays outside this public repository. See also: - [`docs/production-boundaries.md`](docs/production-boundaries.md) - [`docs/reference-topology.md`](docs/reference-topology.md) - [`docs/enterprise-access-layer.md`](docs/enterprise-access-layer.md) - [`SECURITY.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. | Donor | Framework | Key requirements | |---|---|---| | USAID | ADS 201 results framework | Indicators, MEL plan, cost-effectiveness | | EU (INTPA) | EU logframe / intervention logic | OECD DAC criteria, ToC coherence | | World Bank / IFC | PDO + Results Chain | PDO statement, results framework | | GIZ | Technical cooperation results chain | Partner roles, sustainability, capacity | | U.S. State Department | Democracy/diplomacy programme logic | Policy alignment, M&E plan | | FCDO | Logframe (Impact/Outcome/Output) | VfM 4Es, safeguarding, OECD DAC | | AFD | Cadre logique | Climate co-benefit marker, gender marker, French expertise | | JICA | PCM / PDM | Important Assumptions at every level, ODA rationale, tech transfer | | ADB | DMF (Design and Monitoring Framework) | Strategy 2030 OPs, climate finance, gender equity category | All other donors in the catalog (40+) use `GenericDonorStrategy` with a shared results framework. `GET /donors` returns the full catalog and, per donor, `submission_requirements` — the required DOCX sections, XLSX sheets, and ToC sections GrantFlow enforces at export. Fetch it before drafting so output matches the donor's mandated structure. ## 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`](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`](docs/canonical-pilot-path.md) ## Trust Report Before export, the quality surface at `GET /status/{job_id}/quality` includes a `trust_summary` block: ```json { "trust_summary": { "verdict": "export_ready", "export_ready": true, "grounded": true, "critic_passed": true, "hitl_resolved": null, "citations_present": true, "blocking_reasons": [], "governance_flags": { "open_high_severity_finding_count": 0, "open_finding_count": 0, "hitl_pending": false, "export_contract_passed": true, "grounding_risk_level": "low" } } } ``` Agents and buyers read `verdict` to decide whether to proceed to export. It is one of `export_ready`, `needs_review`, `needs_revision`, or `incomplete`. `export_ready` is returned only when every gate passes (terminal + done, critic clear, export contract passed, not awaiting HITL, grounding not failed, and — when `llm_mode` was requested — at least one stage actually used the LLM). Any other verdict means a gate is not cleared; `blocking_reasons` lists exactly which ones. Full trust report and production boundary breakdown: [`docs/agents/trust-report.md`](docs/agents/trust-report.md) ## AI-use disclosure Funders increasingly require disclosure of AI use (for example NIH NOT-OD-25-132 and EU disclosure rules). `GET /status/{job_id}/ai-disclosure` returns a machine-readable record built only from what the job already recorded — `generation_mode` (`deterministic`, `llm_assisted`, or `deterministic_fallback` when `llm_mode` was requested but every stage fell back to deterministic output), `models` (the models actually invoked, empty unless an LLM ran), `grounding` mode and trust signals, `human_review` state, a `boundary` block, and a paste-ready `human_readable` paragraph. It is a transparency record, not a certification of compliance with any funder's policy and not factuality verification. ## Go/No-Go triage Before committing a generation cycle, score funder fit at `POST /decision/bid-no-bid` (with `/decision/bid-no-bid/simulate`). It returns a `BID` / `CONDITIONAL_BID` / `NO_BID` verdict with hard-blocker gates (eligibility, conflict of interest) and `must_fix_before_bid` actions, so an agent does not draft against a poor-fit opportunity. The fit scores are your inputs — GrantFlow does not assess your organization for you. ## Docs Map - Agents: [`AGENTS.md`](AGENTS.md), [`docs/agents/quickstart.md`](docs/agents/quickstart.md), [`docs/agents/mcp.md`](docs/agents/mcp.md), [`docs/agents/error-contract.md`](docs/agents/error-contract.md), [`docs/agents/trust-report.md`](docs/agents/trust-report.md), [`docs/agents/webhook-verification.md`](docs/agents/webhook-verification.md) - Buyers: [`docs/buyer-one-pager.md`](docs/buyer-one-pager.md), [`docs/pilot-evaluation-checklist.md`](docs/pilot-evaluation-checklist.md), [`docs/proof-summary.md`](docs/proof-summary.md) - Operators: [`docs/demo-runbook.md`](docs/demo-runbook.md), [`docs/operations-runbook.md`](docs/operations-runbook.md), [`docs/pilot-day1-checklist.md`](docs/pilot-day1-checklist.md) - Deployment: [`docs/deployment/oauth-gateway.md`](docs/deployment/oauth-gateway.md), [`docs/deployment/credential-revocation.md`](docs/deployment/credential-revocation.md) - Engineers: [`docs/README.md`](docs/README.md), [`docs/architecture.md`](docs/architecture.md), [`docs/contributor-map.md`](docs/contributor-map.md) ## Development Checks ```bash 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.