| --- |
| license: other |
| library_name: custom |
| tags: |
| - code |
| - sovereign-compute |
| --- |
| |
| # Twin-O-Matic |
|
|
| **JIT Browser LLM + Live 3D Engine — No Server, No API Keys, No Install** |
|
|
| [](LICENSE) |
| [](https://snapkittywest.github.io/twin-o-matic/) |
|
|
| --- |
|
|
| ## What Is This |
|
|
| Twin-O-Matic is a browser-based AI agent with tool use. It runs **Llama 3.2 1B** entirely in your GPU via WebLLM/WebGPU and gives the model tools to create **live animated 3D scenes** in real-time. |
|
|
| Open the page. Model loads into VRAM. Type "create a solar system" and watch it appear. |
|
|
| **No server. No API keys. No npm. No install. Just a URL.** |
|
|
| **Live:** https://snapkittywest.github.io/twin-o-matic/ |
|
|
| --- |
|
|
| ## Architecture |
|
|
| ``` |
| ┌─────────────────────────────────────────────────────────────────┐ |
| │ BROWSER │ |
| ├─────────────────────┬───────────────────────────────────────────┤ |
| │ THREE.JS VIEWPORT │ LLM TERMINAL │ |
| │ │ │ |
| │ ┌─────────────┐ │ ┌─────────────────────────────────────┐ │ |
| │ │ WebGL 3D │ │ │ WebLLM (MLC) │ │ |
| │ │ Renderer │ │ │ Llama 3.2 1B q4f16 │ │ |
| │ │ + Orbit │ │ │ WebGPU compute shaders │ │ |
| │ │ Controls │ │ │ │ │ |
| │ └──────┬──────┘ │ └──────────────┬──────────────────────┘ │ |
| │ │ │ │ │ |
| │ ▼ │ ▼ │ |
| │ Scene Engine │ Tool Parser │ |
| │ (primitives, │ (TOOL: lines → 3D objects) │ |
| │ particles, │ │ │ |
| │ lights, │ ▼ │ |
| │ animation) │ Template Fallback │ |
| │ │ (scene detection if model │ |
| │ │ doesn't output tools) │ |
| └─────────────────────┴───────────────────────────────────────────┘ |
| ``` |
|
|
| --- |
|
|
| ## Features |
|
|
| ### Browser LLM (WebGPU) |
| - **Llama 3.2 1B Instruct** quantized to q4f16 — runs entirely client-side |
| - Model weights download once, cached by browser (~700MB) |
| - Streaming inference with live tok/s counter |
| - ~25-120 tok/s depending on GPU |
| - Zero external API calls — all computation is local |
|
|
| ### 3D Tool Use |
| The LLM has tools to create and manipulate a live Three.js scene: |
|
|
| | Tool | Description | |
| |------|-------------| |
| | `add_box` | Rectangular prism with position, size, color | |
| | `add_sphere` | Sphere with radius, position, color | |
| | `add_cylinder` | Cylinder with radius, height, position, color | |
| | `add_torus` | Torus (ring) with radius, tube thickness, color | |
| | `add_cone` | Cone with radius, height, position, color | |
| | `add_particles` | Particle system (count, spread, color) | |
| | `add_light` | Dynamic point light with position, color, intensity | |
| | `set_background` | Change scene background color | |
| | `reset_scene` | Clear all objects | |
|
|
| ### Scene Templates |
| When the model doesn't output tools (1B models are unreliable at structured output), the engine detects scene intent and fires templates: |
|
|
| | Keyword | Scene | |
| |---------|-------| |
| | solar, planet, sun | Solar system with planets, rings, star field | |
| | city, skyline, tower, building | Neon city with varying height towers | |
| | forest, tree, wood, jungle | Trees (cylinder trunks + cone canopies), berries, fireflies | |
| | ocean, sea, water, fish | Ocean plane, fish, sailboat, jellyfish | |
| | space, galaxy, nebula, star | Deep space with nebula particles, planets, rings | |
| | abstract, art, geometric, shape | Nested tori, cones, cylinders, particle clouds | |
|
|
| Any prompt containing "create", "build", "make", "show", "generate", or "draw" also triggers a template if no tools are output. |
|
|
| ### 3D Viewport Controls |
| - **Orbit** — click and drag to rotate camera |
| - **Zoom** — scroll wheel |
| - **Pan** — right-click drag |
| - **Reset Scene** — clear all objects |
| - **Toggle Spin** — stop/start object animation |
| - **Wireframe** — toggle wireframe rendering |
| - **Explode** — fling all objects outward |
| - **Screenshot** — save current frame as PNG |
|
|
| ### Animation |
| All objects float and spin automatically: |
| - Y-axis rotation at varying speeds |
| - Sinusoidal hover (bob up and down) |
| - Each object offset in phase for organic movement |
|
|
| --- |
|
|
| ## How It Works |
|
|
| 1. Page loads → WebGPU adapter detected → model weights stream into GPU |
| 2. User types prompt → sent to Llama 3.2 1B with tool-use system prompt |
| 3. Model outputs `TOOL:` lines → parsed and executed against Three.js scene |
| 4. If model outputs only text → scene detection fires template as fallback |
| 5. Objects appear in viewport with animation |
|
|
| The system prompt includes few-shot examples so the model knows the exact format. The template fallback ensures visuals always appear for scene-creation requests regardless of model output quality. |
|
|
| --- |
|
|
| ## Requirements |
|
|
| - **Chrome 113+** or **Edge 113+** (WebGPU required) |
| - **GPU with 2GB+ VRAM** (model is ~700MB quantized) |
| - That's it. No Node.js. No Python. No server. |
|
|
| --- |
|
|
| ## Run Locally (Optional) |
|
|
| If you want to serve it locally instead of GitHub Pages: |
|
|
| ```bash |
| git clone https://github.com/SNAPKITTYWEST/twin-o-matic.git |
| cd twin-o-matic |
| node server.js |
| # Open http://localhost:8080 |
| ``` |
|
|
| The server is only needed for local development. GitHub Pages serves it statically. |
|
|
| --- |
|
|
| ## TOM: The Recursive Self-Improvement Engine |
|
|
| The Python backend (`tom.py`) is a separate system — a recursive self-improvement loop that uses Ollama for local inference: |
|
|
| ``` |
| ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ |
| │ OUTER LOOP │────▶│ INNER LOOP │────▶│ WORM CHAIN │ |
| │ (analyzes │ │ (executes │ │ (seals each │ |
| │ failures) │◀────│ tasks) │ │ generation)│ |
| └──────────────┘ └──────────────┘ └──────────────┘ |
| ``` |
|
|
| - **Inner Loop** executes tasks with a tunable prompt + hyperparams |
| - **Outer Loop** analyzes telemetry, classifies failures (A/B/C/D), patches the inner prompt |
| - **WORM Chain** seals every generation with SHA-256 (append-only, immutable) |
| - **Assert Gate** validates outer loop patches before promotion (JSON schema, temperature bounds, failure class) |
|
|
| ```bash |
| # Requires Ollama running locally |
| python tom.py --task "write a Python bubble sort" --generations 5 |
| python tom.py --task "prove x^2 >= 0 in Lean 4" --generations 10 |
| ``` |
|
|
| --- |
|
|
| ## Project Structure |
|
|
| ``` |
| twin-o-matic/ |
| ├── index.html # Root redirect → frontend |
| ├── frontend/ |
| │ ├── index.html # Main app (LLM + 3D + tools) |
| │ └── src/ |
| │ └── engine.mjs # Goldilocks field, SHA-256, WORM chain, Lean verifier |
| ├── tom.py # TOM recursive loop (Python + Ollama) |
| ├── prompts/ |
| │ ├── inner_loop.txt # Inner loop system prompt |
| │ └── outer_loop.txt # Outer loop analysis prompt |
| ├── schemas/ |
| │ ├── outer_output_schema.json # Outer loop output validation schema |
| │ └── hyperparams_schema.json # Hyperparameter bounds |
| ├── server.js # Optional local server (WebSocket mesh) |
| ├── .github/workflows/ |
| │ └── deploy.yml # GitHub Pages auto-deploy |
| ├── LICENSE # Sovereign Source License |
| └── README.md # This file |
| ``` |
|
|
| --- |
|
|
| ## Engine Module (engine.mjs) |
|
|
| The frontend includes a pure-JS compute engine with no dependencies: |
|
|
| ### Goldilocks Field Arithmetic |
| All operations mod `p = 2^64 - 2^32 + 1` (the Goldilocks prime used in Plonky2/Miden ZK systems): |
| - `gfAdd(a, b)` — addition mod p |
| - `gfSub(a, b)` — subtraction mod p |
| - `gfMul(a, b)` — multiplication mod p |
| - `gfPow(a, exp)` — exponentiation via square-and-multiply |
| - `gfInv(a)` — inverse via Fermat's little theorem (a^(p-2)) |
|
|
| ### SHA-256 |
| Complete pure-JS implementation. No WebCrypto dependency. Used for WORM sealing. |
|
|
| ### WORM Chain |
| Append-only sealed ledger: |
| - `wormSeal(data)` — hash data + previous seal, append to chain |
| - `wormChain()` — return full chain |
| - `wormVerify()` — verify chain integrity |
|
|
| ### Lean Buffer Verifier |
| Static analysis of Lean 4 buffers: |
| - Sorry count detection |
| - Theorem/lemma declaration detection |
| - Tactic usage analysis (intro, exact, simp, apply, rfl, cases, induction, constructor, rw) |
|
|
| --- |
|
|
| ## Sovereign Stack Integration |
|
|
| Twin-O-Matic connects to the broader SnapKitty sovereign compute constellation: |
|
|
| ``` |
| sov-kernel-monster ← Fortran 2018 quantum density matrix evolution |
| foundry-intel ← WASM proof lab + JIT verification |
| bob-orchestrator ← Lean 4 + Ada + Mamba + Prolog reasoning |
| claudes-harness ← Prolog identity kernel |
| errant ← Linear Forth ISA with QTT |
| sovereign-transformer ← Datalog corpus gate |
| j-matrix-twin ← SUBLEQ attention + J tacit engine |
| twin-o-matic ← THIS — browser LLM + 3D tool use |
| ``` |
|
|
| --- |
|
|
| ## Examples |
|
|
| Try these prompts: |
|
|
| ``` |
| create a solar system |
| build a neon city at night |
| make a forest with glowing particles |
| show me deep space with a nebula |
| create abstract geometric art |
| build a tower made of rings |
| make something beautiful |
| ``` |
|
|
| Or just chat — the model answers questions normally when no scene is detected. |
|
|
| --- |
|
|
| ## Performance |
|
|
| | GPU | Model Load | Inference | |
| |-----|-----------|-----------| |
| | RTX 3080 | ~15s | 80-120 tok/s | |
| | RTX 3060 | ~20s | 50-80 tok/s | |
| | M1 Mac | ~25s | 40-60 tok/s | |
| | Intel Arc | ~30s | 30-50 tok/s | |
| | Integrated | May not work | — | |
|
|
| First load downloads ~700MB of model weights (cached after). |
|
|
| --- |
|
|
| ## License |
|
|
| ``` |
| SOVEREIGN SOURCE LICENSE — Apache 2.0 |
| |
| Copyright 2026 Jessica (SNAPKITTYWEST) |
| All IP belongs to Jessica (jessicalw34@gmail.com) |
| |
| Licensed under the Apache License, Version 2.0 |
| http://www.apache.org/licenses/LICENSE-2.0 |
| ``` |
|
|
| --- |
|
|
| Built with WebLLM + Three.js + WebGPU. No cloud. No telemetry. Sovereign inference. |
|
|
