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