README.md

metadata

title: Backyard Demo Builder
emoji: 🏡
colorFrom: gray
colorTo: green
sdk: gradio
python_version: 3.12.12
app_file: app.py
short_description: Build tiny real-person demos before scaling custom software.
models:
  - unsloth/gemma-4-12B-it-qat-GGUF
  - Qwen/Qwen2.5-7B-Instruct
  - nvidia/Nemotron-3.5-Content-Safety
datasets: []
tags:
  - build-small-hackathon
  - backyard-ai
  - gradio
  - agents
  - small-language-model
  - demo-builder
  - real-estate
  - ai-agents
pinned: false

Backyard Demo Builder

Chapter 1: Backyard AI

Build Small Hackathon 2026 — Chapter 1 Submission

agent-swarm-workbench now presents as Backyard Demo Builder: a Gradio app that turns one real person's workflow into a small runnable demo package before anyone pays to build full software.

First backyard case: my mom, a real-estate agent. She needs a cheap way to test a customer follow-up reminder workflow before committing time and money to a full app.

---

Watch the Demo Builder Work

You:     "Build a real-estate follow-up CRM demo for my mom."
Builder: Generates a Gradio mini-app, handoff spec, field notes, and checks
Result:  app.py, README.md, handoff_spec.md, field_notes.md
Mom:     Tests the workflow, then we scrap or scale.

Every Run produces a downloadable demo package and Validation report: files you can inspect, unzip, run, and test with the real person.

---

Build Small Hackathon — Submission Notes

Requirement	How We Meet It
Small model (≤ 32B)	Provider catalog fetches models at runtime and only allows models whose ID/name proves ≤32B
Gradio app	Custom dark-themed Gradio UI mounted on FastAPI
HF Space	app.py + requirements.txt — one-command deploy
Demo video	(placeholder — [link to demo])
Social post	(placeholder — [link to post])

Bonus Badges Claimed

Badge	Why
🎨 Off-Brand	Fully custom CSS dark theme — Archivo + IBM Plex Mono, acid green CTAs, paper/ink palette, CSS grid layout, status chips. Not a default Gradio component in sight.
📡 Sharing is Caring	Agent traces and swarm reasoning are surfaced in the Events panel. We'll publish a trace on the Hub.
📓 Field Notes	Generated demo packages include field_notes.md; this repo also documents the architecture and decisions.

---

Why This Belongs in Backyard AI

This solves a real problem for someone I know.

• Specific person — my mom, a real-estate agent.
• Specific pain — follow-up reminders and customer-care demos are useful, but custom app dev is slow and risky.
• Honest small-model fit — a ≤32B model drafts the demo and handoff spec; rules handle the reminder logic.
• Actually testable — the generated package includes field notes and feedback questions for the real user.

---

How It Works Under the Hood

┌─────────────────────────────────────────────────────┐
│  Gradio UI / HTTP API                               │
├─────────────────────────────────────────────────────┤
│  RunFlow — lifecycle conductor                      │
│  ┌──────────┐  ┌────────────┐  ┌────────────────┐  │
│  │ Swarm    │  │ Codebase   │  │ Validator      │  │
│  │ Runtime  │→│ Archive    │→│ Graph          │  │
│  │          │  │ Store      │  │                │  │
│  │ Planner  │  │ (local/    │  │ Sandbox checks │  │
│  │ Coder    │  │  Redis)    │  │ Rubric review  │  │
│  │ Reviewer │  │            │  │ Stagehand      │  │
│  │ Tester   │  │            │  │ (Browserbase)  │  │
│  └──────────┘  └────────────┘  └────────────────┘  │
│  EventBus → SSE stream to UI                       │
└─────────────────────────────────────────────────────┘

The Swarm

• Coordinator reads the prompt, plans tasks, delegates to subagents
• Planner breaks down the prompt into implementable units
• Coder writes the actual code files
• Reviewer checks code quality and correctness
• Test-runner runs the user's tests and retries up to 3x on failure
• Validator-prep generates validation checks from user criteria

The Validator

After the swarm finishes, a LangGraph Validator workflow:

1. Restores the codebase into a clean sandbox
2. Runs user-provided tests
3. Executes LLM-based rubric review
4. (Optional) Runs Browserbase/Stagehand visual checks
5. Produces a pass/fail Validation Report

The Sandbox

All agent work happens inside isolated sandbox workspaces:

• Local (for dev/smoke tests)
• Docker (container-based)
• Daytona (cloud sandboxes)

---

Run It

git clone https://github.com/Kiy-K/agent-swarm-workbench.git
cd agent-swarm-workbench
cp .env.example .env
# Optional: add server fallback keys. Users can also paste their own key in the UI.
uv run uvicorn app:app --host 0.0.0.0 --port 8790

Open http://localhost:8790, type a prompt, choose a provider, fetch models with your API key, then click Start Run.

Model selection:

• Model lists are fetched from the selected provider/API endpoint at runtime.
• UI only offers fetched models whose ID/name proves <=32B parameters.
• Unknown-size models are shown in the catalog response as unknown_parameters but are not selectable.
• User API keys and fetched catalogs live only in process memory. They are not persisted, not stored in Redis/DB, and not kept in Gradio state. Click "Refresh models" to clear and refetch that provider cache.

For Hugging Face Spaces:

uv run python app.py

Test

python scripts/task.py verify    # required completion gate: tests + harness
python scripts/task.py test      # 90 tests, all passing
python scripts/task.py harness -- --prompt "Build a tiny CLI" --test "test -f README.md"
python scripts/task.py smoke      # Local agent session smoke check
python scripts/task.py validator-smoke  # Validator end-to-end

Agent Harness

The harness is the fast way to exercise the Run lifecycle without waiting on a full demo session:

python scripts/task.py verify
python scripts/task.py harness -- --prompt "Build a tiny CLI" --output-dir /tmp/harness
python scripts/task.py harness -- --mode live --prompt "Build a tiny CLI"

verify is the required completion gate for coding agents. It runs the Python suite, then runs the default scripted Agent Swarm Harness so changes are checked against the same Run -> SwarmRuntime -> Archive -> Validator path that the app uses.

Modes:

Mode	Purpose
swarm	Default. Runs RunFlow -> SwarmRuntime -> Archive -> Validator with a scripted local DeepAgent-compatible session.
live	Uses the real create_session() DeepAgents path and the configured sandbox provider.

Environment

Var	Purpose
DEEPAGENT_MODEL_PROVIDER	Server fallback model provider: openrouter, gemini, nebius, huggingface, custom, or local
DEEPAGENT_MODEL	Server fallback model ID. Must prove <=32B when selected per Run.
DEEPAGENT_MODEL_BASE_URL	Optional OpenAI-compatible /v1 endpoint
OPENROUTER_API_KEY / GEMINI_API_KEY / NEBIUS_API_KEY / HF_TOKEN	Optional server fallback keys for trusted server/CLI runs only. The public Gradio UI requires the user to enter their own hosted-provider key and does not use these by default.
DEEPAGENT_SANDBOX_PROVIDER	local, docker, or daytona
BROWSERBASE_API_KEY	Optional — visual validation via Stagehand
UPSTASH_REDIS_REST_URL / TOKEN	Optional — persistent runs & archives

---

Stack

• Python 3.11+ / FastAPI / Gradio 6
• LangChain DeepAgents — multi-subagent swarm runtime
• Provider adapters — OpenRouter, Gemini, Nebius, Hugging Face Router, custom OpenAI-compatible, local OpenAI-compatible
• LangGraph — Validator workflow
• QuickJS code interpreter — in-sandbox code execution middleware
• Browserbase + Stagehand — visual web validation (optional)

Architecture

arena/
  agent.py           — Swarm factory, model, subagents, sandbox backend
  backyard_templates.py — Backyard demo template registry
  model_provider.py  — Chat model factory for provider selection
  model_catalog.py   — Provider model list adapters and TTL cache
  swarm_runtime.py   — Active Run registration and Swarm session leasing
  swarm_session.py   — Prompt seeding, agent turns, test retries, snapshots
  sandbox_lease.py   — Idle TTL, touch, and close behavior for sandboxes
  run_flow.py        — Run lifecycle: create → execute → archive → validate
  run_journal.py     — Run mutation journal: status, tasks, events, timestamps
  run_store.py       — Run persistence (InMemory / Redis via Upstash)
  codebase_handoff.py — Workspace snapshot and Validator sandbox restore
  codebase_archive.py — Archive persistence (local / Redis)
  validator_plan.py  — Typed Validator plan from user tests/checks
  validator_graph.py — LangGraph Validator workflow
  thread_inspector.py — Manual Thread/session debug surface
  gradio_app.py      — Thin Gradio component wiring
  gradio_presenter.py — Run output formatting for Gradio
  gradio_markup.py   — Static Gradio shell markup
  api.py             — FastAPI REST + SSE endpoints
  event_bus.py       — In-process event streaming
  browserbase_tools.py  — Web fetch/search tools for the swarm
  stagehand_validator.py — Browserbase visual validation
  docker_backend.py  — Docker sandbox provider
  skill_catalog.py   — Bundled DeepAgents skills discovery
tests_python/        — Python test suite (integration + unit)

---

Built with a sub-32B model for the Build Small Hackathon, June 2026.