Skip to content

README.md

Latest commit

 

History

History
65 lines (46 loc) · 3.1 KB

README.md

File metadata and controls

65 lines (46 loc) · 3.1 KB
Raw

🔌 Circuit Lab - LLM × Wokwi 🤖

A purely-browser playground 🌐 that lets any OpenAI-compatible LLM 🧠 generate complete Wokwi simulation projects 🛠️ (diagram.json, firmware/source, supporting files) from natural-language prompts 💬, and runs them live in an embedded Wokwi simulator ⚡.

The LLM is fully user-supplied 🧑‍💻: you provide a base URL, API key 🔑, and model id - works with OpenAI, OpenRouter, Groq, Ollama, vLLM, LM Studio, Together, DeepInfra, Fireworks, and anything else that speaks /chat/completions 🗣️.

🚀 Run

It's a static site - no build step 🙃.

git clone https://github.com/PythonicVarun/llm-circuit-builder.git
cd llm-circuit-builder
python3 -m http.server 8000
# open http://localhost:8000

Or with any static server (npx serve ., caddy file-server, etc.) 💻.

⚠️ Open over http://localhost (not file://), otherwise the Wokwi iframe can't postMessage back 🛑.

⚙️ How it works

  1. The Wokwi iframe 🖼️ (wokwi.com/experimental/embed) posts a MessagePort 🚪 to the parent on load.
  2. We wrap that port in WokwiClient 📦 (the protocol from wokwi/wokwi-embed-example).
  3. The LLM 🧠 is instructed to reply with a fenced ```wokwi-project JSON block 🧱: 
    {
  "explanation": "…",
  "files": { "diagram.json": "…", "sketch.ino": "…" },
  "start":  { "firmware": "sketch.ino", "elf": "sketch.ino" }
}
  4. Each file is uploaded via file:upload 📤, then sim:start 🎬 kicks off the simulation.
  5. Serial output is streamed back into the on-page monitor 📺.
  6. Every generated file is kept in an on-page file explorer 🗂️ with nested-folder support (so the LLM is free to organise output into src/, lib/, etc.). One click downloads the whole project as a .zip 📦, or you can save any single file.

🛠️ Configure the LLM

Click Settings ⚙️ in the top right. Fields:

Field Example
🔗 API base URL https://api.openai.com/v1
🔑 API key sk-…
🤖 Model ID gpt-4o-mini

Presets are included for OpenAI, OpenRouter, Groq, and Ollama 🎛️. Values are stored in localStorage only 🔒 - nothing leaves your browser except the chat-completion calls themselves 🛡️.

📁 Files

  • 📄 index.html - layout
  • 🎨 styles.css - phosphor-on-slate UI
  • 🧠 app.js - orchestrator (LLM ↔ Wokwi ↔ DOM)
  • 🤖 llm.js - OpenAI-compatible streaming client + system prompt
  • 🗜️ zip.js - zero-dep STORE-method ZIP builder + path-to-tree grouping
  • 🔌 wokwi-client.js, message-port-transport.js, base64.js - Wokwi embed protocol (MIT, CodeMagic LTD)

🙏 Credits

Wokwi embed protocol from https://github.com/wokwi/wokwi-embed-example (MIT, © 2025 CodeMagic LTD) ✨.

📜 License

This project is licensed under the MIT License. ⚖️