@tangle-network/starter-foundry 0.5.4 → 0.7.0

package/registry/families/vllm-server/files/validate-vllm.mjs

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+
+const [serverSource, requirements, config] = await Promise.all([
+  fs.readFile("src/server.py", "utf8"),
+  fs.readFile("requirements.txt", "utf8"),
+  fs.readFile("config.yaml", "utf8"),
+]);
+
+if (!requirements.includes("vllm")) {
+  throw new Error("requirements.txt missing vllm");
+}
+if (!requirements.includes("fastapi") && !requirements.includes("uvicorn")) {
+  throw new Error("requirements.txt must include a Python ASGI framework (fastapi + uvicorn)");
+}
+
+if (!serverSource.includes("AsyncLLMEngine") && !serverSource.includes("LLMEngine") && !serverSource.includes("OpenAIServingChat")) {
+  throw new Error("src/server.py must wire up a vLLM engine or OpenAIServingChat wrapper");
+}
+if (!serverSource.includes("/health")) {
+  throw new Error("src/server.py missing /health route contract");
+}
+
+if (!config.includes("{{modelId}}")) {
+  // Variable substitution happened at compose time — just ensure the model key exists.
+  if (!config.includes("model:")) {
+    throw new Error("config.yaml missing 'model:' section");
+  }
+}
+
+console.log("vllm starter ok");

package/registry/families/vllm-server/manifest.json

@@ -0,0 +1,165 @@
+{
+  "id": "vllm-server",
+  "description": "vLLM-based LLM inference server with OpenAI-compatible endpoints. Production-shape model serving \u2014 PagedAttention memory, continuous batching, quantization-aware. For AI products that serve their own model instead of calling a provider API.",
+  "tags": [
+    "ml",
+    "llm",
+    "inference",
+    "python",
+    "serving",
+    "vllm"
+  ],
+  "taxonomy": {
+    "language": "python",
+    "runtime": "python",
+    "surface": "api"
+  },
+  "slots": {
+    "auth": {
+      "options": [
+        "auth:none",
+        "auth:better-auth",
+        "auth:clerk"
+      ],
+      "default": "auth:none"
+    }
+  },
+  "defaults": {
+    "projectType": "inference",
+    "serviceName": "starter-foundry-vllm",
+    "port": 8097,
+    "modelId": "meta-llama/Meta-Llama-3.1-8B-Instruct",
+    "maxModelLen": 4096
+  },
+  "files": [
+    {
+      "source": "files/requirements.txt",
+      "target": "requirements.txt"
+    },
+    {
+      "source": "files/config.yaml",
+      "target": "config.yaml"
+    },
+    {
+      "source": "files/validate-vllm.mjs",
+      "target": "validate-vllm.mjs"
+    },
+    {
+      "source": "files/README-serving.md",
+      "target": "docs/serving.md"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "src/server.py"
+    },
+    {
+      "type": "file-exists",
+      "path": "requirements.txt"
+    },
+    {
+      "type": "command-success",
+      "command": [
+        "node",
+        "validate-vllm.mjs"
+      ],
+      "expect": "vllm starter ok"
+    }
+  ],
+  "contextHints": {
+    "commands": [
+      "pip install -r requirements.txt",
+      "python -m src.server",
+      "curl http://localhost:{{port}}/v1/chat/completions -H 'Content-Type: application/json' -d '{\"model\":\"{{modelId}}\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}'"
+    ],
+    "entrypoints": [
+      "src/server.py",
+      "config.yaml",
+      "requirements.txt"
+    ],
+    "preview": {
+      "path": "/health"
+    },
+    "extensionPoints": [
+      "config.yaml",
+      "src/middleware/",
+      "src/routes/"
+    ]
+  },
+  "keywords": [
+    "vllm",
+    "llm serving",
+    "llm inference server",
+    "self-hosted llm",
+    "model serving",
+    "openai-compatible api",
+    "paged attention",
+    "continuous batching",
+    "llama",
+    "gpu inference",
+    "inference server",
+    "serve llama"
+  ],
+  "scoring": {
+    "boost": {
+      "vllm": 4,
+      "inference server": 3
+    }
+  },
+  "tieredKeywords": {
+    "tier1": [
+      "vllm",
+      "llm inference server",
+      "self-hosted llm",
+      "model serving"
+    ],
+    "tier2": [
+      "openai-compatible api",
+      "serve llama",
+      "gpu inference",
+      "paged attention",
+      "continuous batching"
+    ],
+    "archetypes": [
+      "private llm host",
+      "on-prem llm",
+      "fine-tuned model deployment",
+      "llm inference platform",
+      "self-hosted chatgpt alternative"
+    ]
+  },
+  "buildHints": {
+    "whenToUse": "Self-hosted LLM inference with OpenAI-compatible endpoints (/v1/chat/completions, /v1/completions, /v1/models). PagedAttention memory, continuous batching. For products that serve their own model instead of calling a provider API.",
+    "firstSteps": [
+      "Install Python deps: `pip install -r requirements.txt`. Requires CUDA 12.1+ + an NVIDIA GPU; vLLM does NOT run on CPU.",
+      "Set the API key: `export VLLM_API_KEY=$(openssl rand -hex 16)` \u2014 the server rejects unauth'd /v1/* without it. To run without auth, set it to empty.",
+      "Edit config.yaml to pick a model. Default is Llama-3.1-8B-Instruct (needs ~16GB VRAM). For 8GB cards add `quantization: awq` and switch to an AWQ-quantized variant.",
+      "Start: `python -m src.server`. First request pulls the model from HuggingFace (multi-minute), then serves.",
+      "Test: `curl http://localhost:{{port}}/v1/chat/completions -H \"Authorization: Bearer $VLLM_API_KEY\" -H \"Content-Type: application/json\" -d '{\"model\":\"{{modelId}}\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}'`",
+      "Prometheus metrics at `/metrics`. Scrape + alert on tokens/sec + active-request count for capacity planning."
+    ],
+    "gotchas": [
+      "vLLM is CUDA-only. No Metal / ROCm / CPU. Attempting to import on a Mac fails at package resolution \u2014 use Modal / RunPod / Lambda / bare-metal for dev.",
+      "First model load takes 1-5 minutes. Keep the container warm; don't rely on autoscale-from-zero unless you budget for cold-start latency.",
+      "The OpenAI SDK expects a real model id string \u2014 `{{modelId}}` gets the HF path after compose. Pass it to the client verbatim.",
+      "Quantization (awq/gptq/fp8) affects output quality. Benchmark against your eval set before deploying quantized to prod.",
+      "For multi-GPU, set `tensor_parallel_size` to the GPU count \u2014 must divide model heads evenly (usually 2, 4, 8)."
+    ],
+    "architectureNotes": [
+      "FastAPI fronts vLLM's AsyncLLMEngine. Adding middleware (rate-limiting, per-user usage meters) is ~10 lines of FastAPI.",
+      "The AsyncLLMEngine instance lives in app.state (set in lifespan). Don't re-instantiate it \u2014 model load is expensive.",
+      "Swap engines by changing the import in server.py + requirements.txt \u2014 OpenAI-compat shape is the same across vLLM / sglang / TGI / ollama."
+    ],
+    "placeholders": [
+      {
+        "path": "config.yaml",
+        "description": "Default points at meta-llama/Meta-Llama-3.1-8B-Instruct. Change `model.id` to the product's actual model (HF path). Adjust quantization + tensor_parallel_size for your hardware."
+      },
+      {
+        "path": "src/server.py",
+        "description": "FastAPI + vLLM wiring. Add product-specific middleware (per-user rate limits, request logging, custom routes) \u2014 the default is a bare OpenAI-compat proxy."
+      }
+    ]
+  }
+}

package/registry/families/voice-first-agent/files/api/README.md

@@ -0,0 +1,83 @@
+# Voice agent backend wiring
+
+This folder is intentionally empty — the browser scaffold posts to three
+routes and expects a backend you stand up yourself. Pick one stack, wire
+the three handlers, point `vite.config.ts` proxy at it. Tangle Router
+(`router.tangle.tools`) is recommended for the LLM call; STT and TTS need
+their own providers.
+
+## Contract
+
+### `POST /api/stt`
+
+**Request:** raw audio blob. `Content-Type` matches what `MediaRecorder`
+produced (`audio/webm;codecs=opus` on Chrome/Firefox, `audio/mp4` on Safari).
+
+**Response:**
+```json
+{ "text": "transcribed words here" }
+```
+
+Providers:
+
+- **Whisper** via `openai` SDK: `openai.audio.transcriptions.create({ file, model: 'whisper-1' })`.
+- **Deepgram** via REST: `POST https://api.deepgram.com/v1/listen` with the raw blob.
+- **AssemblyAI** universal-streaming or `/v2/transcript`.
+- **Self-hosted** `faster-whisper` in a sidecar container if you want zero per-call cost.
+
+### `POST /api/llm`
+
+**Request:**
+```json
+{ "transcript": "what the user said", "history": [...] }
+```
+
+**Response:**
+```json
+{ "reply": "what the agent says back" }
+```
+
+Use `router.tangle.tools` (set `TANGLE_ROUTER_USER_KEY` on the server) so
+you get provider failover and unified billing without vendor lock-in.
+
+### `POST /api/tts`
+
+**Request:**
+```json
+{ "text": "agent reply text" }
+```
+
+**Response:** raw audio bytes. `Content-Type: audio/mpeg` (mp3) is the safest
+bet — every browser decodes it, and the `<audio>` element in `index.html`
+plays it via `URL.createObjectURL(blob)`.
+
+Providers:
+
+- **ElevenLabs** `/v1/text-to-speech/{voice_id}` — lowest latency, best quality.
+- **OpenAI TTS** `audio.speech.create({ model: 'tts-1', voice: 'nova', input })`.
+- **Cartesia** `sonic` for sub-200ms first-chunk latency.
+- **Piper** self-hosted if you want on-device synthesis.
+
+## Minimum viable backend (Node, one file)
+
+```ts
+import express from 'express'
+const app = express()
+
+app.post('/api/stt', express.raw({ type: '*/*', limit: '20mb' }), async (req, res) => {
+  // req.body is the audio Buffer
+  // call your STT provider, return { text }
+})
+
+app.post('/api/llm', express.json(), async (req, res) => {
+  // POST to https://router.tangle.tools/v1/chat/completions
+  // return { reply }
+})
+
+app.post('/api/tts', express.json(), async (req, res) => {
+  // call your TTS provider, stream bytes to res
+  res.setHeader('content-type', 'audio/mpeg')
+})
+
+app.listen(8787)
+```

package/registry/families/voice-first-agent/files/index.html

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>{{headline}}</title>
+    <style>
+      :root { color-scheme: light dark; }
+      body {
+        font-family: system-ui, -apple-system, sans-serif;
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        background: #0a0a0a;
+        color: #f2f2f2;
+      }
+      main { max-width: 520px; padding: 2rem; }
+      h1 { margin: 0 0 0.5rem 0; font-size: 1.4rem; }
+      p.sub { margin: 0 0 2rem 0; color: #888; }
+      button#talk {
+        width: 100%;
+        padding: 1.25rem;
+        font-size: 1.1rem;
+        border: 0;
+        border-radius: 12px;
+        background: #d33;
+        color: white;
+        cursor: pointer;
+        user-select: none;
+        touch-action: none;
+      }
+      button#talk[data-state="recording"] { background: #2a8; }
+      button#talk[data-state="thinking"] { background: #888; cursor: wait; }
+      pre#log {
+        margin-top: 1.5rem;
+        padding: 1rem;
+        background: #111;
+        border: 1px solid #222;
+        border-radius: 8px;
+        font-size: 0.85rem;
+        white-space: pre-wrap;
+        min-height: 6rem;
+        max-height: 18rem;
+        overflow-y: auto;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>{{headline}}</h1>
+      <p class="sub">{{subheadline}}</p>
+      <button id="talk" data-state="idle">Hold to talk</button>
+      <audio id="playback" playsinline></audio>
+      <pre id="log">Ready. Press and hold the button, speak, release.</pre>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/registry/families/voice-first-agent/files/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "validate": "node validate-voice.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "typescript": "^5.9.0",
+    "vite": "^6.4.2"
+  },
+  "overrides": {
+    "vite": "^6.4.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "^6.4.2"
+    }
+  }
+}

package/registry/families/voice-first-agent/files/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/**/*.ts", "vite.config.ts"]
+}

package/registry/families/voice-first-agent/files/validate-voice.mjs

@@ -0,0 +1,46 @@
+// Structural validator for voice-first-agent. Does NOT open a browser or
+// call getUserMedia — just cross-checks the scaffold wiring is coherent.
+
+import fs from "node:fs/promises";
+import { stripTypeScriptTypes } from "node:module";
+
+const [pkgSource, indexHtml, mainTs, viteConfig] = await Promise.all([
+  fs.readFile("package.json", "utf8"),
+  fs.readFile("index.html", "utf8"),
+  fs.readFile("src/main.ts", "utf8"),
+  fs.readFile("vite.config.ts", "utf8"),
+]);
+
+const pkg = JSON.parse(pkgSource);
+if (pkg.name !== "{{packageName}}") {
+  throw new Error(`package.json name should be "{{packageName}}", got "${pkg.name}"`);
+}
+
+if (!indexHtml.includes('id="talk"')) {
+  throw new Error("index.html missing #talk button — voice UI contract");
+}
+if (!indexHtml.includes('id="playback"')) {
+  throw new Error("index.html missing <audio id=\"playback\"> element for TTS playback");
+}
+
+if (!mainTs.includes("MediaRecorder")) {
+  throw new Error("src/main.ts must use MediaRecorder — browser-native audio capture");
+}
+if (!mainTs.includes("getUserMedia")) {
+  throw new Error("src/main.ts must call navigator.mediaDevices.getUserMedia to request mic access");
+}
+if (!mainTs.includes("isTypeSupported")) {
+  throw new Error("src/main.ts must call MediaRecorder.isTypeSupported before picking a MIME type (Safari compatibility)");
+}
+if (!mainTs.includes("/api/stt") || !mainTs.includes("/api/llm") || !mainTs.includes("/api/tts")) {
+  throw new Error("src/main.ts must POST to /api/stt, /api/llm, /api/tts — the wiring contract");
+}
+
+if (!viteConfig.includes("/api")) {
+  throw new Error("vite.config.ts must proxy /api to the backend during dev");
+}
+
+// main.ts must be parseable TypeScript.
+stripTypeScriptTypes(mainTs);
+
+console.log("voice-first-agent starter ok");

package/registry/families/voice-first-agent/files/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite'
+
+// Dev-server proxy forwards /api/* to whatever you wire in api/README.md
+// (Whisper proxy, LLM endpoint, TTS endpoint). Swap the target for your
+// backend URL when you stand one up.
+export default defineConfig({
+  server: {
+    port: {{port}},
+    proxy: {
+      '/api': {
+        target: 'http://localhost:8787',
+        changeOrigin: true,
+      },
+    },
+  },
+})

package/registry/families/voice-first-agent/manifest.json

@@ -0,0 +1,140 @@
+{
+  "id": "voice-first-agent",
+  "description": "Browser-first voice agent scaffold — MediaRecorder captures mic audio, POSTs to /api/stt for transcription, /api/llm for the response, /api/tts for speech synthesis, then plays the returned audio. Zero SDK lock-in: raw Web APIs in the browser, server-side wiring is pluggable.",
+  "tags": [
+    "voice",
+    "audio",
+    "agent",
+    "browser",
+    "frontend",
+    "typescript",
+    "vite"
+  ],
+  "taxonomy": {
+    "language": "typescript",
+    "runtime": "browser",
+    "surface": "frontend"
+  },
+  "defaults": {
+    "projectType": "frontend",
+    "serviceName": "starter-foundry-voice-agent",
+    "port": 4180,
+    "headline": "Push-to-talk voice agent",
+    "subheadline": "Hold the button, speak, release. STT → LLM → TTS round-trip in the browser."
+  },
+  "files": [
+    {
+      "source": "files/package.json",
+      "target": "package.json"
+    },
+    {
+      "source": "files/tsconfig.json",
+      "target": "tsconfig.json"
+    },
+    {
+      "source": "files/vite.config.ts",
+      "target": "vite.config.ts"
+    },
+    {
+      "source": "files/index.html",
+      "target": "index.html"
+    },
+    {
+      "source": "files/validate-voice.mjs",
+      "target": "validate-voice.mjs"
+    },
+    {
+      "source": "files/api/README.md",
+      "target": "api/README.md"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "src/main.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "index.html"
+    },
+    {
+      "type": "command-success",
+      "command": [
+        "node",
+        "validate-voice.mjs"
+      ],
+      "expect": "voice-first-agent starter ok"
+    }
+  ],
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "pnpm run dev"
+    ],
+    "entrypoints": [
+      "index.html",
+      "src/main.ts",
+      "api/README.md",
+      "vite.config.ts"
+    ],
+    "preview": {
+      "path": "/"
+    },
+    "extensionPoints": [
+      "src/main.ts",
+      "api/"
+    ]
+  },
+  "keywords": [
+    "voice first",
+    "voice first agent",
+    "browser voice agent",
+    "push to talk",
+    "mediarecorder agent",
+    "speech to text agent",
+    "speech agent scaffold",
+    "browser mic agent",
+    "whisper client",
+    "voice ui scaffold"
+  ],
+  "scoring": {
+    "boost": {
+      "voice first": 4,
+      "mediarecorder": 3,
+      "push to talk": 3
+    }
+  },
+  "tieredKeywords": {
+    "tier1": [
+      "voice first",
+      "voice first agent",
+      "browser voice agent",
+      "push to talk"
+    ],
+    "tier2": [
+      "mediarecorder",
+      "speech to text agent",
+      "browser mic",
+      "whisper client",
+      "voice ui scaffold"
+    ],
+    "archetypes": [
+      "walkie-talkie web",
+      "voice memo to ai",
+      "hold-to-talk chatbot",
+      "voice notes transcriber",
+      "browser voice recorder with llm",
+      "spoken-input chat ui"
+    ]
+  },
+  "buildHints": {
+    "gotchas": [
+      "getUserMedia requires HTTPS outside localhost. Any non-localhost deployment behind plain HTTP will fail with NotAllowedError — either ship behind TLS or use a tunneled HTTPS URL for dev.",
+      "MediaRecorder MIME support varies by browser: Safari prefers audio/mp4, Chrome/Firefox prefer audio/webm;codecs=opus. Always call MediaRecorder.isTypeSupported() before `new MediaRecorder(stream, {mimeType})` or the constructor throws on Safari.",
+      "Safari autoplay policies block new Audio().play() without a prior user gesture. Trigger playback from the button click handler, not from a fetch .then() callback that may resolve after the gesture context expires.",
+      "Holding the stream open between turns drains the mic LED and frightens users. Call track.stop() on each track when the recording ends; re-request via getUserMedia on the next press.",
+      "Blob size after 10s of 48kHz opus is ~80KB — safe to POST as raw body. Do NOT base64-encode into a JSON field (1.33× payload bloat + parser overhead). Use fetch with blob body and Content-Type from recorder.mimeType.",
+      "iOS Safari requires playsinline on <audio> playback in some contexts and silently suppresses volume control — verify on a real device, simulator behaves differently."
+    ]
+  }
+}

package/registry/families/wasm-rust/files/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "{{crateName}}"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+# cdylib is required for wasm-bindgen output. rlib so native unit tests
+# still work against the same source.
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+wasm-bindgen = "0.2"
+
+[profile.release]
+opt-level = "s"
+lto = true
+codegen-units = 1
+
+[profile.dev]
+opt-level = 1

package/registry/families/wasm-rust/files/build-wasm.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Build the Rust crate to WASM using wasm-pack. Requires wasm-pack on PATH:
+//   curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+//
+// Output lands under ./pkg/ with type declarations + a loader module that
+// Vite picks up via vite-plugin-wasm.
+
+import { spawnSync } from "node:child_process";
+
+const result = spawnSync(
+  "wasm-pack",
+  ["build", "--target", "web", "--out-dir", "pkg", "--release"],
+  { stdio: "inherit" },
+);
+
+if (result.error) {
+  console.error(
+    "wasm-pack not found. Install with:\n  curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh",
+  );
+  process.exit(1);
+}
+process.exit(result.status ?? 0);

package/registry/families/wasm-rust/files/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build:wasm": "node build-wasm.mjs",
+    "dev": "pnpm run build:wasm && vite",
+    "build": "pnpm run build:wasm && vite build",
+    "preview": "vite preview",
+    "validate": "node validate-wasm.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "typescript": "^5.9.0",
+    "vite": "^6.4.2",
+    "vite-plugin-wasm": "^3.5.0",
+    "vite-plugin-top-level-await": "^1.6.0"
+  },
+  "overrides": {
+    "vite": "^6.4.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "^6.4.2"
+    }
+  }
+}

package/registry/families/wasm-rust/files/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowJs": true,
+    "lib": ["ESNext", "DOM"]
+  },
+  "include": ["src/**/*.ts", "vite.config.ts"]
+}