GrantFlow

From solicitation files to a reviewable proposal package.

Upload a solicitation and an existing draft for assessment, or give GrantFlow the source material for a new proposal workflow. GrantFlow returns:

• a structured bid/no-bid decision from operator-owned scores;
• a file-based draft assessment with a prioritized reviewer queue;
• a donor-aware first draft;
• a prioritized list of evidence and review gaps;
• a .docx, .xlsx, or ZIP package for human review.

GrantFlow supports two delivery paths:

• Outcome pilot for proposal teams — I run the workflow for a scoped grant opportunity and hand back the reviewable package. No API integration is required.
• Agent-first infrastructure for builders — MCP and HTTP interfaces for teams embedding governed proposal operations in their own systems.

Scope an outcome pilot · Run the hosted demo · Read the agent contract

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.

Outcome pilot

The current offer is a bounded paid pilot for one active or recently completed institutional grant opportunity. It is being tested; no paying customers or completed external pilots are claimed.

Your team provides the solicitation, organization facts, prior proposal material, and a named reviewer. I operate GrantFlow and return the bid/no-bid memo, first reviewable draft, blocking findings, evidence gaps, AI-use disclosure, and export package.

The buyer still owns factual accuracy, eligibility, final editing, approvals, and submission. Do not email confidential documents before file handling and retention are agreed.

Pilot scope, fit, deliverables, and contact

Product direction

GrantFlow applies four current product shifts to institutional proposal work:

• Document-data workflows: PDF, DOCX, TXT, and Markdown solicitation/draft pairs go straight into a provenance-preserving assessment rather than a copy-and-paste chat.
• Agent-native infrastructure: machine-readable HTTP and MCP interfaces let agents discover the workflow, assess files, pause for review, and export the same governed result.
• Vertical AI collaboration: the output is a bounded reviewer queue and editable evidence package, so the collaboration layer—not autonomous prose generation—is the product surface.
• AI-native service delivery: the initial commercial path delivers a completed, inspectable proposal-operations package instead of another writing copilot.

This is document text extraction, not general multimodal understanding: image-only PDFs require OCR, and image/video analysis is not implemented. The outcome pilot tests whether buyers will pay for the result. Trend alignment is not evidence of demand. Directional references: YC Requests for Startups and a16z Big Ideas 2026: Part 1. The source-to-claim check is recorded in docs/trend-alignment-claim-ledger.md.

Who is this for?

NGO, implementer, and grant-consulting teams with an active or recent EU or UN opportunity, source material that can support the draft, and a named person who can review and reject the output.

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: assured funding outcomes, automated donor submission, eligibility or compliance determinations, unsupervised proposal generation, or teams that cannot provide source material and human review.

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

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 (20 tools):

• grantflow_onboard_agent
• grantflow_create_session
• grantflow_introspect_agent
• grantflow_exchange_oauth_token
• grantflow_rotate_credential
• grantflow_revoke_credential
• grantflow_register_agent
• grantflow_decide_bid_no_bid
• grantflow_simulate_bid_no_bid
• grantflow_assess_draft
• 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

This is the inverse of the generation pipeline. Give it a donor solicitation and an existing proposal draft. It returns possible submission risks, missing evidence, unresolved questions, and the first 20 findings a reviewer should inspect.

POST /assess is enabled by default. Set GRANTFLOW_ASSESSMENT_ENABLED=false only when an operator needs to remove the assessment surface from a deployment.

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

For PDF, DOCX, UTF-8 TXT, or Markdown files, use the multipart path:

curl -X POST http://127.0.0.1:8000/assess/files \
  -F donor_id=eu \
  -F [email protected] \
  -F [email protected]

The default path is deterministic and makes no model call. To inspect contradictions and cited claims across an evidence pack, opt in explicitly and attach up to eight supporting documents:

curl -X POST http://127.0.0.1:8000/assess/files \
  -F donor_id=eu \
  -F adjudication_mode=model \
  -F [email protected] \
  -F [email protected] \
  -F [email protected] \
  -F [email protected]

This mode requires an OpenAI-compatible provider key. A dedicated model can be set with GRANTFLOW_ASSESSMENT_MODEL; otherwise GrantFlow tries the configured reasoning and cheap models. The semantic input is capped at 80,000 combined characters. Missing credentials, oversized input, or provider failure preserves the deterministic result and reports deterministic_fallback rather than hiding the failure. Opting in sends the complete draft, complete supporting-document texts, and extracted requirement quotes to the configured provider; the full solicitation is not sent. Do not use model mode for confidential material until provider retention and handling terms are acceptable. The response records this under adjudication.data_sent_to_model.

Before that provider call, GrantFlow scans only the model-bound draft, supporting texts, and requirement quotes for explicit English-language high-signal instruction overrides, role changes, prompt or credential exfiltration requests, review-control bypasses, and embedded chat control tokens. A match returns blocked_suspected_prompt_injection, preserves the deterministic assessment, and reports exact spans under adjudication.input_safety; no model call occurs. A clear scan is not proof that a document is safe: indirect, multilingual, or unseen attacks and generation inputs remain outside this assessment gate. New RAG sources have a separate ingest-time quarantine described below; already-indexed content can be inspected through the separate read-only audit described there. Reported signal quotes remain untrusted caller input and must not become downstream instructions. Free-form model rationale is discarded; reviewer findings retain only server-authored text and exact quotes re-anchored to caller-supplied documents.

To hand the result to a reviewer, use the matching export path and choose docx, xlsx, or zip. The ZIP pack contains the formatted report, editable compliance matrix, source assessment JSON, and a SHA-256 manifest.

curl -X POST 'http://127.0.0.1:8000/assess/files/export' \
  -F donor_id=eu \
  -F format=zip \
  -F [email protected] \
  -F [email protected] \
  --output grantflow-assessment.zip

For exact text inputs, call POST /assess/export?format=zip with the same JSON body accepted by POST /assess. Export files repeat the assessment verdict; they do not recalculate or upgrade it.

The response returns the exact extracted strings, source filenames, media types, and SHA-256 hashes under input_documents; citation spans index into those returned strings. Each file is capped at 25 MiB by default (GRANTFLOW_MAX_ASSESSMENT_UPLOAD_BYTES), and each extracted document at 400,000 characters (GRANTFLOW_MAX_ASSESSMENT_DOCUMENT_CHARS). Scanned/image-only PDFs are rejected with an OCR next action because GrantFlow does not perform OCR.

Agents can call the same path as grantflow_assess_draft. Use grantflow_decide_bid_no_bid first when the team has operator-owned fit scores, and grantflow_simulate_bid_no_bid only for sensitivity analysis. GrantFlow does not infer those scores from the documents. When API auth is enabled, the assessment credential needs assess:write.

Returns a compliance matrix, findings with severity and remediation, unresolved questions, a triage summary grouped by solicitation section and broad reviewer domain, 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 in repository fixtures. The default path is fully deterministic: no model is called, the same documents always produce the same result, and a run costs nothing. Against the repository's synthetic EU/INTPA fixture it finds 5 of 8 seeded defects with no false accusations. Independent synthetic USAID-style and FCDO-style fixtures each score 5 of 5 seeded deterministic defects with zero control requirements falsely marked unsupported. Against a published 34-page EuropeAid call it extracted 86 obligations in 11 ms with all spans verifying byte-exactly. These are regression measurements, not user validation or donor endorsement.

Optional cross-document adjudication. adjudication_mode=model can add two bounded finding classes: direct contradictions between supplied documents and explicit citations that do not support the associated draft claim. The model cannot set severity or verdict. Each accepted finding needs two verbatim quotes that the server resolves back to exact spans, carries model and confidence metadata, and still requires human review. Hallucinated quotes, low-confidence output, unlinked citation claims, and prompt instructions inside documents are rejected by contract tests. The offline control suite repeats that path across synthetic EU/INTPA, USAID-style, and FCDO-style packs: all 6 injected valid relationships retain exact spans and all 9 invalid controls are rejected. Run it with make eval-assessment-cross-document. This measures server validation of injected candidates, not whether a model can discover them; live-provider precision and recall are not tested.

make eval-assessment-input-safety runs a separate offline gate: 5/5 high-signal adversarial packs are quarantined before the injected invoker, two benign/output-minimization controls pass, all reported signal spans resolve exactly, and model rationale is absent from public output. The suite uses synthetic text and no provider. It does not measure indirect or multilingual attacks, generation-input prompt injection, RAG attacks beyond the separate ingest gate below, or live-model behavior.

make eval-rag-source-integrity exercises the same narrow detector on the RAG ingest boundary. Across repository fixtures, 5/5 explicit high-signal sources are quarantined before chunking or indexing, while 2/2 benign controls are indexed with source_integrity_status=clear and retrieval_eligible=true. Quarantine returns exact spans (and page numbers for PDF), keeps the source out of retrieval, and remains visible in ingest audit/inventory without increasing readiness corpus counts. This is an offline synthetic control: it does not detect indirect, multilingual, encoded, or unseen attacks; certify a clear source; rescan legacy corpus; or measure a live model or embedding provider.

POST /ingest/source-integrity/audit scans one bounded page of chunks already stored in a tenant/donor namespace. It reports exact chunk-local spans, legacy metadata counts, pagination, and whether the requested page can establish a complete namespace result. It never deletes or rewrites vectors. Operators must scan every page and remediate suspect content separately; the same detector and limitations apply.

Still not implemented. Full semantic adjudication of every donor requirement remains out of scope for this layer. Roughly 40% of obligations on the real call could not be evaluated by deterministic lexical matching. Long calls can still produce dozens of findings, so the response includes a severity-ordered triage.review_queue capped at 20 active items, plus explicit counts for findings left outside that queue; the full finding list remains available. Requirements and findings carry a deterministic review_domain such as finance, monitoring and evaluation, or safeguarding and risk. These domains organize review and exports but never alter status, severity, or verdict; their lexical classification has not been validated by users. 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.
• New text/PDF RAG sources with explicit English high-signal prompt-injection-like patterns are quarantined before indexing. A clear scan is not a security or factuality guarantee.
• 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.

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 review

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.