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

```bash
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:
```bash
uv run python app.py
```

## Test

```bash
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:

```bash
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.*