ProofFlow Agent

ProofFlow turns binding hackathon rules and live project artifacts into a strict, judge-ready evidence ledger. It autonomously ingests an official Devpost rules page, scans a public GitHub repository, probes the deployment, asks Gemini 3.6 Flash for schema-constrained requirement reasoning, uses Gemma 4 to select one validated operational priority through a forced function call, measures that action's risk alignment with Gemini Embedding 2, persists the result in Firestore, and exports a portable Markdown evidence pack.

Built from scratch for the All Things Agentic Hackathon in the Taskmaster category.

Live proof

• Submitted entry: ProofFlow on Devpost
• Product: proofflow-agent.vercel.app
• Public demo video (1:48): youtu.be/kqhoyUaeGdI
• Firestore-backed health: proofflow-agent.vercel.app/api/health
• Latest Gemma + embedding audit: JSON · Markdown evidence pack · passing production trace
• Gemma-prioritized audit: JSON · Markdown evidence pack
• Cloud deployment evidence: docs/CLOUD_PROOF.md
• Build-window provenance: docs/BUILD_PROVENANCE.md
• Gemini XPRIZE business narrative: docs/XPRIZE_SUBMISSION.md
• Truthful profit and loss statement: docs/xprize-profit-and-loss.csv

The public demo was created for the purposes of entering the All Things Agentic Hackathon and includes on-screen narration, a production audit, the evidence ledger, system architecture, and live Google Cloud/Firestore proof.

Why it exists

Submission compliance is a messy, high-stakes last-mile workflow. Requirements are scattered across rules, overview pages, repository documentation, deployment dashboards, and video checklists. A generic chatbot can summarize those sources, but it does not prove which obligations are actually satisfied.

ProofFlow performs the workflow:

1. validates and fingerprints the binding rules;
2. inspects the repository tree and README through GitHub's public API;
3. probes the supplied deployment;
4. uses Gemini structured output to map requirements to concrete evidence;
5. asks Gemma 4 to select one existing next action without inventing or rewriting it;
6. uses Gemini Embedding 2 to measure the selected action against the validated risk list;
7. records the immutable run in a private-by-default Firestore database; and
8. exposes a downloadable evidence pack with precise next actions.

Missing evidence stays missing. The model never receives credentials and the browser never receives the Gemini or Firebase keys.

Gemma Core (isolated competition mode)

/gemma-core is a separate, free rate-limited public-source workflow for the autonomous-agent competition track. It collects the same bounded Devpost, public GitHub, and optional deployment sources, but uses only gemma-4-26b-a4b-it for semantic reasoning. Gemma is forced to return one bounded function call containing an audit parsed again with the existing Zod audit schema and one index into its own existing next-action list.

The mode fails closed when a rules excerpt is absent from the collected rules, when a missing requirement claims evidence, or when verified/partial evidence is not an observed repository file/README/repository URL or observed deployment URL. Rules text can establish an obligation but cannot by itself verify implementation. Its Firestore records are labeled auditMode: "gemma-core" with the exact model identifier. The existing homepage, POST /api/analyze, and paid POST /api/v1/audits remain the Gemini-first workflow described above; Gemma is core only on /gemma-core.

Architecture

The Next.js server runs the bounded orchestration layer. Firebase Admin access is server-only. Firestore client rules remain production-mode/private. Public usage is capped globally and per pseudonymous daily client hash.

Sponsor technology

• Gemini 3.6 Flash through the official Google GenAI SDK (@google/genai), with Gemini 3.5 Flash Lite as a standards-compliant availability fallback
• Gemma 4 26B through the same SDK for function-bound operational prioritization; failure preserves the validated first action deterministically
• Gemini Embedding 2 through the same SDK for a 128-dimensional semantic-grounding check; failure never changes the validated audit or priority
• Cloud Firestore in the proofflow-agent Firebase project
• Next.js 16 and React 19 on Vercel
• Zod schema validation and Vitest

Local spin-up

Requirements: Node.js 22 or newer, a Gemini API key, and a Firebase service-account key for a Firestore-enabled project.

npm install
cp .env.example .env.local

Set:

• GEMINI_API_KEY to a server-only Gemini API key;
• FIREBASE_SERVICE_ACCOUNT_BASE64 to the base64-encoded service-account JSON; and
• RATE_LIMIT_SECRET to a long random value.

Then run:

npm test
npm run dev

Open http://localhost:3000. The default inputs point to this project's contest rules and public repository.

Production deployment

1. Create a Vercel project from this repository.
2. Add the three server-only environment variables listed above.
3. Deploy the main branch.
4. Call GET /api/health and confirm both ok and firestore.
5. Run one audit through the UI and download /api/runs/{id}/report.

Never commit the service-account JSON or expose it through a NEXT_PUBLIC_ variable.

API

POST /api/analyze

{
  "rulesUrl": "https://allthingsagentichackathon.devpost.com/rules",
  "repoUrl": "https://github.com/ArgonautWorks/proofflow-agent",
  "projectUrl": "https://proofflow-agent.vercel.app"
}

Other routes:

• POST /api/gemma-core — isolated Gemma Core audit; same bounded input shape, free daily rate limit, and 10KB body cap;
• GET /api/runs/{id} — retrieve a persisted audit;
• GET /api/runs/{id}/report — download its Markdown evidence pack; and
• GET /api/health — verify the server and Firestore path.

Paid agent API

The free UI remains available for evaluation. Autonomous buyers can request higher-priority machine-readable audits through POST /api/v1/audits for $0.05 USDC on Base using x402 v2. The paid handler validates the sources, checks capacity, and completes model inference before settlement; invalid inputs, capacity failures, and upstream model errors are not charged. GET /api/v1/audits returns free machine-readable purchase instructions; only POST is paid.

Discovery is available at /openapi.json, /.well-known/x402, and /llms.txt. Payments settle directly to the ArgonautWorks receiving wallet without an account, subscription, or API key.

The public origin also exposes /robots.txt and /sitemap.xml. Significant landing-page changes can be submitted to participating search engines with npm run notify:indexnow; the notifier first verifies the deployed ownership key and never treats an accepted indexing request as traffic or revenue.

Free agent discovery is also available at /.well-known/agent-card.json and POST /a2a. The A2A transport returns purchase instructions only: it never invokes Gemini, creates an audit, or initiates payment.

• x402scan service page
• PayanAgent relay offer
• Agent Tools paid-service card
• Agent Tools A2A card
• A2A Registry verified agent

Directory records and unpaid challenge probes are distribution evidence, not revenue.

As of the XPRIZE submission package on August 5, 2026, ProofFlow has recorded no external users, paying users, revenue, or expenses. Internal tests, operator runs, directory probes, and judging activity are excluded from those figures. The public P&L above is the canonical disclosure until independently settled revenue is observed.

Guardrails

• official Devpost rules pages and public GitHub repository roots only;
• Vercel or Devpost deployment probes only;
• no arbitrary URL fetching, repository writes, or user-supplied prompts;
• strict request size and daily capacity limits;
• primary model output constrained by JSON Schema and revalidated with Zod;
• Gemma can select only an existing validated action index through a forced function call; and
• Gemma Core additionally rejects unobserved excerpts, file paths, and rule-only implementation claims; and
• the optional embedding stage compares only the selected action with at most five validated risks; and
• no raw client IP storage.

License

Apache-2.0