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.

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:

# 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:

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": 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
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

Discover capabilities and tools.
Onboard credentials or register a sandbox agent identity.
Run donor/readiness preflight.
Start deterministic generation with an idempotency key.
Poll status or consume webhook callbacks.
Inspect quality, grounding, citations, and audit events.
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"
  }'

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

Draft Compliance Assessment (experimental)

Inverse of the generation pipeline: instead of drafting, it ingests a donor solicitation and a proposal draft the applicant has already written, and reports what would disqualify them.

Off by default. Set GRANTFLOW_ASSESSMENT_ENABLED=true to register the route; without it POST /assess returns 404 and nothing else changes.

curl -X POST http://127.0.0.1:8000/assess \
  -H 'Content-Type: application/json' \
  -d '{"donor_id":"eu","solicitation_text":"...","draft_text":"..."}'

Returns a compliance matrix, findings with severity and remediation, unresolved questions, a triage summary, pilot metrics, and a readiness verdict (export_ready, needs_review, needs_revision, incomplete). Character spans in the response index into the exact strings you submitted, so every citation resolves against your own copy of the documents.

Findings carry a five-state status. insufficient_evidence means the requirement could not be judged from the documents supplied — it is never a statement of non-compliance, and a missing annex is reported as unknown rather than as a failure.

Implemented and measured. Fully deterministic: no model is called, the same documents always produce the same result, and a run costs nothing. Against the repository's own EU/INTPA fixture it finds 5 of 8 seeded defects with no false accusations. Against a published 34-page EuropeAid call it extracted 86 obligations in 11 ms with all spans verifying byte-exactly.

Not implemented. Cross-document reasoning — whether a cited source actually supports a claim, or whether two documents contradict each other — is out of reach for the deterministic layer and is not built. Roughly 40% of obligations on the real call could not be evaluated, because matching is lexical. Findings are not yet ranked well enough for a long call: that run produced 67 findings, which is more than a reviewer will read. See docs/pilot-readiness-audit.md §13 for the full measurement, including what it did not resolve.

Not validated with users. No NGO team has run this against a real proposal of their own.

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.

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.

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": "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

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, 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.

Grantflow

README