NetBud

Self-hosted network design accomplice. Upload customer requirements after a meeting; NetBud's orchestrator splits the brief by section, derives a shared architectural baseline, then runs designer/critic agent pairs in parallel for LAN, WAN, EDGE, CLOUD, and QOS — coherence-checking the results so the five designs actually fit together. Approved sections turn into Containerlab / GNS3 sandboxes via the same conversational build agent that's been here since v1.

Homelab-first, single-user, opinionated. Not a multi-tenant SaaS. Project-specific conventions live in CLAUDE.md — read that for the why-it's-built-this-way context.

What it does

Intake — drag-drop a typed PDF/Word/Markdown, paste meeting notes, or upload a photo of a whiteboard. Typed text is parsed in-process; images and scanned material go through a vision LLM for faithful transcription (no separate OCR service). The extractor pulls the customer ID off a Customer: <id> line and splits the document into LAN / WAN / EDGE / CLOUD / QOS buckets.

Orchestrator — derives a shared architectural baseline (routing family, AS numbers, IP plan, QoS classes, security posture, cloud connectivity) from the brief + retrieved guidelines. Then spawns one designer/critic loop per populated section, running them as concurrent background tasks. After each round it runs a coherence pass that flags cross-section conflicts (LAN's voice CoS not matching QOS's class map, WAN routing protocol clashing with EDGE assumptions, etc.) and forces the offending section to revise. Capped at 2 coherence rounds.

Designer / Critic pair (unchanged from v1, now baseline-constrained):

• Designer queries a ChromaDB corpus of network design guidelines, proposes a design with mandatory citations, writes the rationale as markdown (with an embedded mermaid topology diagram). Decisions it can't source are flagged as unsourced, never fabricated.
• Critic independently re-queries Chroma to verify each citation in code (the LLM doesn't grade its own homework), then hunts for design flaws. Strictness is user-controlled (1–5).
• Hard cap of 5 iterations per section. Streamed to the UI so you can watch designs materialise.

Slack integration — when SLACK_BOT_TOKEN is set, NetBud DMs you on every lifecycle event (run started, baseline ready, section ready, coherence conflict, run complete). Add SLACK_SIGNING_SECRET plus an Events API registration at https://<your-tunnel>/slack/events and you can DM the bot or @-mention it to ask questions about completed designs — Q&A only, no design runs from Slack.

Build agent — takes any approved section design and turns it into a conversational sandbox build:

• Decides per-turn whether to ASK a clarifying question (specific subnets, vendor preference, routing details) or BUILD.
• Produces a topology spec, deterministic per-node configs (Cisco IOS / FRR), and three artifact exports:
  • draw.io XML (open in your existing diagrams.net instance)
  • Containerlab YAML
  • GNS3 project skeleton
• Lab-only by design. Push to gear is gated by a lab-inventory file and an explicit dry-run → confirm flow. No production targets.

Other features

• Multi-provider LLM router (Anthropic / OpenAI / xAI / DeepSeek / Ollama) — pick a different model per agent. Anthropic Sonnet is the default.
• Persistent SQLite store (data/netbud.sqlite) covers customers, briefs, runs, section designs, builds, and the build journal.
• HTML / DOCX export of any saved legacy design (full prose + diagram + citations table).
• Interactive Cytoscape topology graph in the sandbox view; click a node to see its config, dry-run, and confirm-push.
• PWA shell — installable on iOS/Android home screens (Add to Home Screen). Service worker caches the app shell so the customer list still loads on a flaky connection.

Architecture

backend/  FastAPI · SQLite (SQLModel) · ChromaDB v2 HTTP API · sentence-transformers embeddings
  app/
    intake/      text_parser (pypdf/docx/md/txt) · vision_parser (Claude vision) · extractor (LLM)
    agents/      orchestrator · designer · critic · loop · conversational build agent
    rag/         chroma client (query, citation verification)
    llm/         multi-provider router (anthropic/openai/xai/deepseek/ollama)
    topology/    configgen · containerlab · gns3 · drawio · pusher (netmiko)
    db/          SQLModel tables · session · legacy import
    slack/       outbound notifier · inbound /slack/events Q&A handler
    export/      markdown → HTML/DOCX (pandoc)
    api/         intake · runs · customers · design · build · journal · models · health · gns3
    jsonblock.py robust JSON extraction (handles streaming truncation)

frontend/  Vite · React 19 · React Router · Tailwind 4 · cytoscape · mermaid · react-markdown · PWA

The stack mirrors the Gladius family conventions; the UI follows Kopis's design tokens. NetBud doesn't run its own ChromaDB — it connects to the existing one on the shared net_core Docker network.

Run it

Prereqs: Docker, the existing net_core external network, ChromaDB on net_core with a design-guidelines collection.

cd C:\docker\net-core\netbud
docker compose up -d --build

Cloudflare tunnel routes https://netbud.clydeford.net → netbud-frontend over net_core. For local-only access, copy docker-compose.override.yml.example → docker-compose.override.yml to publish ports to the host.

Dev mode:

# Backend
cd backend && uvicorn app.main:app --reload --host 0.0.0.0 --port 8080

# Frontend
cd frontend && npm install && npm run dev

Configuration

Everything secret + environment-specific is in .env at the repo root (gitignored). See app/config.py for the full list. Required for full functionality:

• CLAUDE_API_KEY (or ANTHROPIC_API_KEY) — default model is Sonnet
• OPENAI_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY — optional, enable those providers
• OLLAMA_URL, OLLAMA_MODEL — optional, enables local models
• CHROMA_HOST, CHROMA_PORT — defaults to chroma-db:8000 on net_core
• NETBUD_LAB_INVENTORY — path to lab inventory YAML (see lab-inventory.example.yaml)
• SLACK_BOT_TOKEN, SLACK_TARGET — outbound notifications (channel or user ID)
• SLACK_SIGNING_SECRET — additionally needed for inbound Q&A at /slack/events

Providers without keys are disabled in the model selector so missing-key errors never reach the request path.

Lab inventory & push safety

The build agent's pusher refuses any node not present in the lab inventory file. Two-step UX: dry-run shows the generated config alongside the inventory entry; only then does the "Confirm push" button activate. Every dry-run and push is appended to the SQLite build_journal table.

Migrating from the flat-file era

Pre-pivot, designs and builds were stored as JSON files under data/designs/ and data/builds/ with data/build_journal.jsonl for the audit log. SQLite is the source of truth from this version on; the legacy files are not touched at runtime. To pull them into the new schema:

docker exec -it netbud-backend python -m app.db.legacy_import

Imported designs land under a synthetic LEGACY customer with section_name=FULL, accessible from the Customers page. The original files are left in place.

Layout philosophy

• Customer-first landing — /customers lists who you've designed for, with the per-run section breakdown one click away.
• Upload page — drag-drop on desktop, camera capture on mobile (whiteboard photos go straight through vision).
• Active run — section panels showing each designer/critic pair's progress with the orchestrator's baseline pinned on top.
• Sidebar nav — collapsible to a 64px icon rail (preference persisted).
• Compose / Designs / Sandbox — the legacy direct-brief flow remains for one-shot designs that don't need the orchestrator.

What it isn't

• Not a multi-tenant SaaS (Gladius-family pattern: opinionated, single-user, self-hosted).
• Not a Slack-first product — Slack handles notifications and Q&A; runs are kicked off in the web/PWA only.
• Not a production change-management tool — sandbox / lab gear only.
• Not cyberpunk-themed — that's Gladius. NetBud is Kopis-family visually.

Files of interest

• CLAUDE.md — project conventions, what-this-is-and-isn't, why decisions were made the way they were.
• backend/app/agents/orchestrator.py — baseline derivation, parallel section runs, coherence pass.
• backend/app/intake/extractor.py — LLM-driven customer ID extraction + section split.
• backend/app/db/models.py — SQLite/SQLModel schema (customers, briefs, runs, sections, builds, journal).
• backend/app/slack/notifier.py · backend/app/slack/events.py — outbound notifications + inbound Q&A.
• backend/app/agents/designer.py · critic.py — designer system prompt + critic strictness logic (per-section, baseline-constrained).
• backend/app/jsonblock.py — JSON extraction with truncation recovery.
• frontend/src/pages/Upload.jsx · CustomerList.jsx · CustomerDetail.jsx · ActiveRun.jsx — new orchestrator flow pages.