GrantFlow

Agent-native grant workflow infrastructure for autonomous 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.

---

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
• Sandbox agent registration via POST /agents/register
• Self-serve agent onboarding via POST /agents/onboarding
• 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"

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"]
  }'

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.

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:

• grantflow_onboard_agent
• grantflow_register_agent
• grantflow_run_preflight
• grantflow_start_generation
• grantflow_get_status
• grantflow_get_quality
• grantflow_get_events
• 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 autonomous 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 is API-key based.
• Enterprise IAM/OIDC/SAML/RBAC should sit at the gateway/platform layer.
• 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

Buyer Proof

Current strongest proof paths:

• EU
• UN
• USAID as conditional, depending on use case and operating constraints

Pilot offer:

• ICP: NGO/implementer teams with recurring EU/UN 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 Map

• Agents: AGENTS.md, docs/agents/quickstart.md, docs/agents/mcp.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
• Engineers: docs/README.md, docs/architecture.md, docs/contributor-map.md

Development Checks

uv run pytest
uv run mypy grantflow
uv run ruff check .
uv run python scripts/api_contract_guard.py

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