TraceFrame

TraceFrame is a generative-media operations console backed by a FastAPI service. It records a canonical Genblaze manifest for each run, stores media by content hash, and can re-read the durable manifest and asset bytes to verify their integrity.

The default package is an honest local demo. It uses the official Genblaze pipeline with a deterministic provider, writes synthetic PNGs to a local Docker volume, and labels seeded output as synthetic. It does not contact OpenAI or Backblaze B2 and requires no credentials.

Current validation boundary

• The local API, deterministic provider, local content-addressed storage, manifest verification, and frontend workflow are implemented and covered by their component test suites.
• The B2 adapter and OpenAI adapter are implemented behind configuration gates. A real account smoke test is still required before claiming that either integration has been validated live.
• This repository does not claim a public deployment. The Compose package binds both services to loopback by default.

Architecture

React/Vite console -> FastAPI -> Genblaze Pipeline -> deterministic demo provider
                              |                    -> gated OpenAI DalleProvider
                              |
                              +-> SQLite projection
                              +-> local content-addressed storage
                              +-> gated Backblaze B2 ObjectStorageSink

The backend is authoritative for provider, storage, manifest, and verification state. The frontend does not ship fabricated media records or infer that B2 is active.

Run the local demo with Docker Compose

Requirements: Docker Engine and Docker Compose 2.24 or newer.

docker compose up --build

Open:

• Operator console: http://localhost:5173
• OpenAPI: http://localhost:8000/docs
• Readiness: http://localhost:8000/readyz

The API data is retained in the traceframe-data Docker volume. Stop the services with docker compose down. Removing the volume with docker compose down --volumes also removes the local demo database and generated objects.

Port overrides are optional:

TRACEFRAME_API_PORT=8080 TRACEFRAME_WEB_PORT=5174 docker compose up --build

In PowerShell, set those values as environment variables before running Compose.

Run from source

Backend requirements and commands are documented in backend/README.md. Frontend requirements and commands are documented in frontend/README.md.

cd backend
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"
.venv/Scripts/python -m uvicorn traceframe.app:app --host 127.0.0.1 --port 8000

On macOS and Linux, use .venv/bin/python instead. In a second terminal:

cd frontend
npm ci
npm run dev

Authorized live smoke

Live generation is disabled by default. It requires all of the following explicit settings:

• TRACEFRAME_PROVIDER=openai
• TRACEFRAME_LIVE_GENERATION_ENABLED=true
• TRACEFRAME_SEED_DEMO=false
• a non-empty API bearer secret and OpenAI API key
• complete Backblaze B2 credentials and a non-empty API bearer secret when TRACEFRAME_STORAGE_MODE=b2

See DEPLOYMENT.md for the bounded, fail-closed live-smoke procedure and deployment limits. Never commit a populated environment file. Starting the configured API performs a B2 readiness canary but does not call OpenAI; only the explicitly authorized smoke client invokes the paid model.

Verification commands

docker compose config --quiet

cd backend
.venv/Scripts/python -m pytest
.venv/Scripts/python -m ruff check .
.venv/Scripts/python -m mypy src/traceframe

cd ../frontend
npm test
npm run lint
npm run build

Use .venv/bin/ instead of .venv/Scripts/ on macOS and Linux.

License

Apache License 2.0. See LICENSE.