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

• Product: proofflow-agent.vercel.app
• Public demo video (1:48): youtu.be/kqhoyUaeGdI
• Firestore-backed health: proofflow-agent.vercel.app/api/health
• Latest live audit: JSON · Markdown evidence pack
• Cloud deployment evidence: docs/CLOUD_PROOF.md
• Build-window provenance: docs/BUILD_PROVENANCE.md

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. records the immutable run in a private-by-default Firestore database; and
6. 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.

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

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

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.

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;
• model output constrained by JSON Schema and revalidated with Zod; and
• no raw client IP storage.

License

Apache-2.0