README.md

metadata

title: Backblaze ProofFrame
sdk: docker
app_port: 8088

ProofFrame

ProofFrame is a provenance-first generative media vault for the Backblaze Generative Media Hackathon.

It turns a creative brief into a reviewable asset packet: generated media, prompt history, model/provider metadata, hashes, approval state, and a shareable manifest. The local demo uses deterministic generation and local storage; the final hackathon gate is to verify the same packet flow through Genblaze-backed generation and Backblaze B2-compatible storage. The product goal is not "yet another image generator"; it is the missing operations desk for teams that need to know where an AI asset came from, whether it is approved, and how to reproduce or retire it.

Hackathon Choice

Selected competition: Backblaze Generative Media Hackathon

Public mock demo: Hugging Face Space Judge Mode (credential-free local/mock mode; final B2 and Genblaze live proof remains gated).

Why this one:

• Online Devpost format with a clear August 3, 2026 5:00 PM EDT deadline, which is August 4, 2026 05:00 in Beijing.
• Cash prizes, including a $7,000 grand prize.
• Moderate visible participant count compared with larger AI agent events.
• Sponsor requirements are specific enough to reward meaningful integration: Genblaze plus Backblaze B2.
• A polished, useful product can beat a raw model demo here.

Judge Quickstart

For a 60-second review path:

1. Open the public judge-mode demo.
2. Read the first-screen Sponsor Evidence Model and fail-closed gate status.
3. Use the one-click Judge Demo packet if it does not auto-load.
4. Inspect the generated asset ledger, manifest preview, approval state, checksum, and evidence ZIP.
5. Treat the public run as local/mock mode: B2 and Genblaze integration code paths are present, but live B2/Genblaze proof remains the final gate before sponsor-complete claims.

Copy-ready judge brief: docs/assets/judge-brief.md. Official criteria crosswalk: docs/assets/judge-crosswalk.md.

Core Documents

• docs/research.md: competition search, candidate comparison, selected-event evidence.
• docs/prd.md: product PRD.
• docs/spec.md: technical specification.
• docs/integrations.md: B2 and Genblaze readiness gates.
• docs/deployment.md: public demo deployment runbook.
• docs/devpost_draft.md: copy-ready Devpost draft with claim gates.
• docs/demo_script.md: demo video script and shot list.
• docs/evidence_package.md: Devpost evidence package and copy bank.
• docs/public_claim_freeze.md: public claim boundaries before final submission.
• docs/verification.md: local, Docker, live proof, and secret-scan runbook.
• docs/submission.md: registration and submission plan.
• docs/todo.md: human task board.
• tasks.json: queryable task ledger.

Local Task Commands

python3 scripts/task.py list
python3 scripts/task.py list --status todo
python3 scripts/task.py search Genblaze --status doing
python3 scripts/task.py show T001
python3 scripts/task.py add T099 "Record final demo" --phase "P4 Submit" --owner controller --after T041
python3 scripts/task.py done T001
python3 scripts/task.py blocked T010 --note "Requires account setup"

Planned Stack

• Backend: Python, FastAPI, SQLite.
• Storage: local storage for offline demo, Backblaze B2 S3-compatible storage for submission.
• Generation: deterministic mock provider for local tests, Genblaze/OpenAI-compatible media provider adapter for real runs.
• Frontend: production-grade browser UI with apps/web/index.html as entry point.
• Packaging: Dockerfile and release checklist.

Current Status

Stage 0 is complete: selected competition, repo, PRD/spec/todo, Agent Bus team, official-rule scout report, and GitHub setup.

Stage 1 is complete enough for local demo iteration: FastAPI MVP skeleton, mock generation, local storage, manifest export, downloadable evidence packets, one-click Judge Demo packets, and the Proof Ledger browser UI.

Stage 2 is in progress: B2-compatible storage code and Genblaze image provider paths for GMICloud, OpenAI, and a credential-free local Pipeline provider exist. In final B2 mode, the Genblaze path now uses the official ObjectStorageSink plus S3StorageBackend.for_backblaze so Genblaze provenance output can land in B2 before ProofFrame records its own packet manifest. Final B2 plus local Genblaze Pipeline proof is captured in docs/assets/final-live-proof-evidence.json; public video, final audit, and Devpost receipt remain submission gates.

Stage 3 preparation is active: the public mock demo is deployed, Review Console polish is captured, Devpost/evidence/claim-freeze docs are ready for the final sponsor-integration pass, API evidence exports fail closed if secret-like values appear, and the app now displays a fail-closed submission gate dashboard, judge recording slate, criteria crosswalk, recording runbook, Devpost kit, and submit checklist for final task/live-proof status.

Run Locally

python3.11 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev,integrations]"
pytest
uvicorn proofframe.app:app --reload --port 8088

Then open http://127.0.0.1:8088/.

Integration Readiness

. .venv/bin/activate
python scripts/check_integrations.py
python scripts/genblaze_contract_check.py
python scripts/docker_smoke.py
python scripts/live_proof.py --preflight-only
python scripts/run_final_live_proof.py --env-file .env.final.local --preflight-only
python scripts/run_final_live_proof.py --env-file .env.final.local --genblaze-provider local --genblaze-image-model local-svg-v1 --preflight-only
python scripts/live_env_handoff.py
python scripts/final_env_wizard.py --check-only
python scripts/b2_key_scope_checklist.py
python scripts/devpost_form_kit.py
python scripts/devpost_submission_checklist.py
python scripts/judge_brief.py
python scripts/judge_crosswalk.py
python scripts/judge_decision_brief.py
python scripts/devpost_event_snapshot.py --validate-committed
python scripts/agent_handoff_check.py
python scripts/public_space_upload.py
python scripts/public_space_sync.py --wait-attempts 5 --wait-seconds 30
python scripts/claim_lint.py
python scripts/demo_storyboard.py
python scripts/demo_video_draft.py --build-video
python scripts/public_video_check.py
python scripts/sponsor_fit_audit.py
python scripts/demo_readiness.py
python scripts/recording_assets.py
python scripts/award_readiness.py --min-score 75
python scripts/final_submission_control.py
python scripts/final_closeout_status.py
python scripts/final_operator_brief.py
python scripts/final_launch_plan.py
python scripts/submission_audit.py
python scripts/devpost_submission_receipt.py
python scripts/devpost_packet.py
python scripts/submission_bundle.py

The browser UI and GET /api/submission/gate expose the same fail-closed final gate: required task status, Devpost packet presence, final B2/Genblaze evidence readiness, and the final secret scan, submission audit, and Devpost receipt reports. scripts/submission_bundle.py creates a safe manifest of public submission artifacts, screenshots, checksums, Devpost copy mode, and remaining gate blockers. scripts/live_env_handoff.py creates a redacted B2/Genblaze credential handoff report so final proof setup can be checked without printing keys. scripts/public_space_upload.py dry-runs the Hugging Face Space upload plan by default, excludes local env files and runtime folders, and can execute the upload only after the no-secret preflight passes. scripts/genblaze_contract_check.py verifies the installed Genblaze/B2 SDK import and signature contract without reading environment variables or credential files, catching package/API drift before live keys are entered. scripts/docker_smoke.py verifies the Docker image builds, starts in local/mock mode, passes API smoke, and uses .dockerignore to keep local env files out of the build context. scripts/final_env_wizard.py creates a local git-ignored .env.final.local with 0600 permissions, can prefill non-secret B2/default values, reads existing local values as defaults, and uses hidden prompts for credential values. Its --check-only mode is a no-secret readiness preflight for git-ignore status, .env.final.local presence, chmod 0600, missing or placeholder variable names, and B2 region derivation. scripts/b2_key_scope_checklist.py creates a no-secret B2 app-key scope checklist for the dedicated bucket, prefix, required upload capability, S3 SDK compatibility flag, forbidden permissions, and stop conditions before a key is created. scripts/run_b2_live_proof.py verifies the Backblaze B2 storage path independently with mock generation, so T020 can close before Genblaze credentials are ready. scripts/devpost_form_kit.py turns the safe packet into field-by-field Devpost copy with length checks, a strict final gate, and an in-app Devpost Kit through GET /api/judge/devpost. scripts/devpost_submission_checklist.py turns the final form kit into an ordered, no-secret Devpost web submission checklist with preflight gates, copy order, stop rules, post-submit receipt commands, and an in-app Submit Checklist through GET /api/judge/submission-checklist. scripts/judge_brief.py condenses the current public demo, award posture, safe claims, and final blockers into a 30-second judge brief. scripts/judge_crosswalk.py maps official judging criteria and submission requirements to current evidence, safe claims, final gates, and demo shots; the browser UI exposes the same map through GET /api/judge/crosswalk. scripts/judge_decision_brief.py builds the one-page judge decision card behind GET /api/judge/decision-brief, summarizing why to score ProofFrame highly, what public evidence is green, and which final gates remain without overclaiming. scripts/judge_evidence_index.py builds the public-safe evidence index behind GET /api/judge/evidence-index, collecting the judge brief, criteria crosswalk, decision brief, final gate, Devpost preview, recording assets, and live-proof gates without changing safe_to_submit=false. scripts/final_rehearsal.py turns the final operator brief, launch plan, public sync, and gates into a no-secret final-submission rehearsal checklist. scripts/devpost_event_snapshot.py keeps official Devpost deadline, participants, submission requirements, and judging criteria as a refreshable evidence report. scripts/agent_handoff_check.py keeps AGENTS.md, Codex, and Agent Bus handoff paths aligned with the current repo so future role sessions do not follow stale project metadata. scripts/public_space_sync.py verifies the public Hugging Face Space runtime sha, raw handoff, Devpost event snapshot, final launch plan, B2 key scope checklist, Genblaze SDK contract report, judge brief, judge crosswalk, judge decision brief, judge evidence index, final closeout status, final video publish kit, mock video draft, public video check, health/gate APIs, and judge-mode HTML markers. scripts/run_final_live_proof.py is the final one-command live runner: once B2 and Genblaze env vars are present, it starts the app, verifies /api/health reports b2 plus genblaze, routes Genblaze output through the B2 sink, writes sanitized final evidence, and stops the server. The non-secret --genblaze-provider and --genblaze-image-model flags let the operator switch from the default gmicloud path to the credential-free local Genblaze Pipeline provider without editing .env.final.local or printing keys. scripts/claim_lint.py keeps pre-live public copy from claiming completed Backblaze B2 or Genblaze proof before evidence exists. scripts/secret_scan.py writes a no-value secret scan report for public files, generated evidence, local logs, and media inventory while excluding local credential files without reading them. scripts/demo_storyboard.py keeps the demo video timeline under 3 minutes and tracks the public video URL as a final gate. scripts/demo_video_draft.py builds a public-safe mock MP4 draft from committed screenshots for rehearsal, while explicitly keeping safe_to_submit=false and final_video_ready=false. scripts/final_video_publish_kit.py prepares final upload title, description, chapters, allowed hosts, and the Devpost video field gate without marking the video ready before the public URL passes. scripts/public_video_check.py verifies the final public demo video URL is non-placeholder, token-free, hosted on an allowed Devpost public video family (YouTube, Vimeo, or Youku), and reachable before final submission. scripts/sponsor_fit_audit.py checks that Backblaze B2 and Genblaze are explained as product-critical sponsor paths without overclaiming live proof. scripts/demo_readiness.py keeps the mock demo recording package ready while failing strict final mode until live B2/Genblaze proof and the final secret scan are complete. scripts/recording_assets.py checks committed recording assets, powers the in-app Recording Runbook through GET /api/judge/recording, and can run GET-only public demo verification without creating data or using secrets. scripts/award_readiness.py scores sponsor fit, provenance depth, demo readiness, claim safety, and final closure so polish work stays aligned with judge expectations. scripts/final_submission_control.py aggregates the gate, form kit, storyboard, credential handoff, and award reports into one final Devpost control tower. scripts/final_closeout_status.py summarizes final live proof, public video, Devpost, secret scan, audit, bundle, and receipt gates into one no-secret closeout report with the next command to run. scripts/final_operator_brief.py turns the remaining live-proof blockers into a no-secret handoff: user actions, Codex follow-up commands, and safety policy. scripts/final_launch_plan.py turns the final operator brief and gate reports into a no-secret phased launch checklist from credential entry through Devpost receipt. scripts/submission_audit.py writes a schema-stamped pre-submit audit report and only passes strict mode after live proof, final scan, public video, and submit-ready copy are synchronized. scripts/devpost_submission_receipt.py records the final public Devpost /software/<slug> URL and confirmation note after submission, without cookies or private form data.

B2 mode intentionally fails closed unless B2_ENDPOINT_URL, B2_BUCKET, B2_KEY_ID, and B2_APPLICATION_KEY are set. Final Genblaze+B2 proof also requires a B2 region, either via B2_REGION or a standard Backblaze S3 endpoint such as https://s3.us-west-004.backblazeb2.com. Genblaze mode intentionally fails closed unless GENBLAZE_PROVIDER is gmicloud, openai, or local, the required provider key is present for external providers, GENBLAZE_IMAGE_MODEL is set, and the official genblaze-core, provider, and genblaze-s3 packages are installed.

Submission Verification

The repository also runs the same core checks in GitHub Actions on main, feature/**, and pull requests.

. .venv/bin/activate
python scripts/check_integrations.py
python scripts/genblaze_contract_check.py
ruff check .
pytest
python scripts/api_smoke.py --base-url http://127.0.0.1:8088
python scripts/secret_scan.py
python scripts/claim_lint.py
python scripts/live_env_handoff.py
python scripts/final_env_wizard.py --check-only
python scripts/b2_key_scope_checklist.py
python scripts/devpost_form_kit.py
python scripts/devpost_submission_checklist.py
python scripts/judge_brief.py
python scripts/judge_crosswalk.py
python scripts/judge_decision_brief.py
python scripts/devpost_event_snapshot.py --validate-committed
python scripts/agent_handoff_check.py
python scripts/public_space_sync.py
python scripts/demo_storyboard.py
python scripts/demo_video_draft.py
python scripts/public_video_check.py
python scripts/demo_readiness.py
python scripts/recording_assets.py
python scripts/final_operator_brief.py
python scripts/final_launch_plan.py

See docs/verification.md for Docker and live B2/Genblaze proof commands.