@tangle-network/starter-foundry 0.5.3 → 0.7.0

package/registry/layers/framework/rag-pipeline-py/files/pipeline.py

@@ -0,0 +1,220 @@
+"""End-to-end RAG pipeline.
+
+Usage:
+    python -m src.pipeline index            # (re)build the Chroma collection
+    python -m src.pipeline ask "question"   # retrieve + answer
+
+Swap the LLM by pointing LLM_BASE_URL at any OpenAI-compatible server
+(Ollama's /api/chat is auto-detected from the base URL).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Iterable
+
+import httpx
+from dotenv import load_dotenv
+
+# langchain-text-splitters is re-exported from langchain-community in older
+# pins; import the modern path first.
+try:
+    from langchain_text_splitters import RecursiveCharacterTextSplitter
+except ImportError:  # pragma: no cover — fallback for older installs
+    from langchain.text_splitter import RecursiveCharacterTextSplitter  # type: ignore
+
+import chromadb
+from chromadb.config import Settings
+from sentence_transformers import SentenceTransformer
+
+load_dotenv()
+
+DOCS_DIR = Path(os.environ.get("DOCS_DIR", "./docs"))
+VECTOR_DB_DIR = Path(os.environ.get("VECTOR_DB_DIR", "./chroma_db"))
+EMBEDDING_MODEL = os.environ.get("EMBEDDING_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
+LLM_BASE_URL = os.environ.get("LLM_BASE_URL", "http://localhost:11434")
+LLM_MODEL = os.environ.get("LLM_MODEL", "llama3.1:8b")
+CHUNK_SIZE = int(os.environ.get("CHUNK_SIZE", "800"))
+CHUNK_OVERLAP = int(os.environ.get("CHUNK_OVERLAP", "120"))
+TOP_K = int(os.environ.get("TOP_K", "4"))
+
+COLLECTION_NAME = os.environ.get("COLLECTION_NAME", "rag-docs")
+
+
+def _load_docs(root: Path) -> list[tuple[str, str]]:
+    """Return (source_path, text) pairs for every supported file under root."""
+    results: list[tuple[str, str]] = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        suffix = path.suffix.lower()
+        if suffix in {".md", ".txt"}:
+            results.append((str(path), path.read_text(encoding="utf-8")))
+        elif suffix == ".pdf":
+            try:
+                from pypdf import PdfReader  # lazy — only needed if PDFs exist
+            except ImportError as exc:  # pragma: no cover
+                raise RuntimeError(
+                    "PDF ingest requires `pip install pypdf` (or `pip install -e .[pdf]`)."
+                ) from exc
+            text = "\n".join(page.extract_text() or "" for page in PdfReader(str(path)).pages)
+            results.append((str(path), text))
+    return results
+
+
+def _chunk(text: str) -> list[str]:
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=CHUNK_SIZE,
+        chunk_overlap=CHUNK_OVERLAP,
+        separators=["\n\n", "\n", ". ", " ", ""],
+    )
+    return splitter.split_text(text)
+
+
+def _embedder() -> SentenceTransformer:
+    return SentenceTransformer(EMBEDDING_MODEL)
+
+
+def _client() -> chromadb.PersistentClient:
+    VECTOR_DB_DIR.mkdir(parents=True, exist_ok=True)
+    return chromadb.PersistentClient(
+        path=str(VECTOR_DB_DIR),
+        settings=Settings(anonymized_telemetry=False, allow_reset=True),
+    )
+
+
+def index() -> int:
+    """Ingest DOCS_DIR into Chroma. Rebuilds the collection from scratch."""
+    if not DOCS_DIR.exists():
+        print(f"DOCS_DIR {DOCS_DIR} does not exist", file=sys.stderr)
+        return 1
+    docs = _load_docs(DOCS_DIR)
+    if not docs:
+        print(f"No ingestible docs under {DOCS_DIR}", file=sys.stderr)
+        return 1
+
+    embedder = _embedder()
+    client = _client()
+    # Idempotent: delete + recreate so re-indexing never mixes stale chunks.
+    try:
+        client.delete_collection(COLLECTION_NAME)
+    except Exception:
+        pass
+    collection = client.create_collection(
+        name=COLLECTION_NAME,
+        metadata={"hnsw:space": "cosine"},
+    )
+
+    chunks: list[str] = []
+    metadatas: list[dict[str, str]] = []
+    ids: list[str] = []
+    for source, text in docs:
+        for i, chunk in enumerate(_chunk(text)):
+            chunk_id = f"{source}::{i}"
+            chunks.append(chunk)
+            metadatas.append({"source": source, "chunk": str(i)})
+            ids.append(chunk_id)
+
+    vectors = embedder.encode(chunks, batch_size=32, show_progress_bar=False).tolist()
+    collection.add(documents=chunks, embeddings=vectors, metadatas=metadatas, ids=ids)
+    print(f"Indexed {len(chunks)} chunks from {len(docs)} docs into {VECTOR_DB_DIR}")
+    return 0
+
+
+def retrieve(query: str, k: int = TOP_K) -> list[tuple[str, str, float]]:
+    """Return (chunk_text, source, cosine_distance) for the top-k matches."""
+    embedder = _embedder()
+    collection = _client().get_collection(COLLECTION_NAME)
+    query_vec = embedder.encode([query]).tolist()
+    # similarity_search — Chroma reports distance (lower is better for cosine).
+    result = collection.query(query_embeddings=query_vec, n_results=k)
+    docs = result["documents"][0]
+    metas = result["metadatas"][0]
+    dists = result["distances"][0]
+    return [
+        (str(d or ""), str((m or {}).get("source", "?")), float(dist))
+        for d, m, dist in zip(docs, metas, dists)
+    ]
+
+
+def _llm_chat(system: str, user: str) -> str:
+    """Call the configured LLM. Auto-detect Ollama vs OpenAI-compatible."""
+    is_ollama = "11434" in LLM_BASE_URL or LLM_BASE_URL.rstrip("/").endswith("/api")
+    if is_ollama:
+        url = LLM_BASE_URL.rstrip("/") + "/api/chat"
+        payload = {
+            "model": LLM_MODEL,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            "stream": False,
+        }
+        with httpx.Client(timeout=httpx.Timeout(120.0, connect=10.0)) as client:
+            response = client.post(url, json=payload)
+            response.raise_for_status()
+            body = response.json()
+        return body["message"]["content"]
+
+    # OpenAI-compatible fallback.
+    url = LLM_BASE_URL.rstrip("/") + "/v1/chat/completions"
+    payload = {
+        "model": LLM_MODEL,
+        "messages": [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+    }
+    headers = {}
+    api_key = os.environ.get("LLM_API_KEY")
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    with httpx.Client(timeout=httpx.Timeout(120.0, connect=10.0)) as client:
+        response = client.post(url, json=payload, headers=headers)
+        response.raise_for_status()
+        body = response.json()
+    return body["choices"][0]["message"]["content"]
+
+
+def ask(question: str) -> str:
+    """Retrieve top-k chunks and synthesize an answer with inline citations."""
+    hits = retrieve(question)
+    if not hits:
+        return "No documents indexed. Run `python -m src.pipeline index` first."
+    context_blocks: list[str] = []
+    for chunk, source, _distance in hits:
+        context_blocks.append(f"[doc:{Path(source).name}]\n{chunk}")
+    context = "\n\n---\n\n".join(context_blocks)
+    system = (
+        "You answer questions using ONLY the provided context. "
+        "Cite every claim with the [doc:filename] marker from the matching "
+        "passage. If the context does not contain the answer, say so plainly."
+    )
+    user = f"Context:\n{context}\n\nQuestion: {question}"
+    return _llm_chat(system, user)
+
+
+def _usage() -> int:
+    print("usage: python -m src.pipeline {index | ask <question>}", file=sys.stderr)
+    return 2
+
+
+def main(argv: Iterable[str]) -> int:
+    args = list(argv)
+    if not args:
+        return _usage()
+    cmd, *rest = args
+    if cmd == "index":
+        return index()
+    if cmd == "ask":
+        if not rest:
+            return _usage()
+        print(ask(" ".join(rest)))
+        return 0
+    return _usage()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/registry/layers/framework/rag-pipeline-py/manifest.json

@@ -0,0 +1,56 @@
+{
+  "id": "rag-pipeline-py",
+  "description": "Framework layer for rag-pipeline-py — ships the ingest + retrieve + answer pipeline (src/pipeline.py) and an AGENTS.md guide for AI-agent consumption.",
+  "appliesTo": ["rag-pipeline-py"],
+  "files": [
+    { "source": "files/pipeline.py", "target": "src/pipeline.py" },
+    { "source": "files/__init__.py", "target": "src/__init__.py" },
+    { "source": "files/AGENTS.md", "target": "AGENTS.md" }
+  ],
+  "buildHints": {
+    "whenToUse": "Apply to any rag-pipeline-py starter to get the full ingest → chunk → embed → Chroma → retrieve → LLM pipeline in a single src/pipeline.py file.",
+    "firstSteps": [
+      "pip install -e . — installs langchain-core, langchain-text-splitters, chromadb, sentence-transformers, httpx, and python-dotenv",
+      "cp .env.example .env — then set LLM_BASE_URL to a running Ollama server (ollama serve) or any OpenAI-compatible endpoint",
+      "Drop source docs (.md / .txt / .pdf) into docs/",
+      "python -m src.pipeline index — builds the Chroma collection from docs/",
+      "python -m src.pipeline ask 'your question here' — retrieves and answers"
+    ],
+    "gotchas": [
+      "Changing EMBEDDING_MODEL invalidates the Chroma collection — delete VECTOR_DB_DIR and re-run index.",
+      "Ollama must be running before ask — start with `ollama serve` and pull the model with `ollama pull llama3.1:8b`.",
+      "PDF ingest requires `pip install pypdf` (or `pip install -e .[pdf]`) — not included in the base install.",
+      "The collection is rebuilt from scratch on every index run — intentional to avoid stale chunks."
+    ],
+    "architectureNotes": [
+      "pipeline.py is the single entrypoint: index() chunks and embeds all docs into Chroma; ask() embeds the query, retrieves top-k chunks, and calls the LLM with a grounded system prompt.",
+      "All tuneable parameters (chunk size, top-k, model names, paths) are read from environment variables — override in .env without touching code.",
+      "LLM routing is auto-detected: URLs containing :11434 or ending in /api use Ollama's /api/chat; all others use OpenAI-compatible /v1/chat/completions."
+    ],
+    "placeholders": [
+      {
+        "path": "src/pipeline.py",
+        "description": "Tune CHUNK_SIZE, CHUNK_OVERLAP, and TOP_K via .env (or change the defaults at the top of the file) to match your corpus density and desired retrieval precision."
+      },
+      {
+        "path": ".env",
+        "description": "Set LLM_BASE_URL to a running Ollama server or any OpenAI-compatible endpoint; set LLM_MODEL to the model you have pulled; leave EMBEDDING_MODEL unchanged unless you need a different embedding dimensionality."
+      },
+      {
+        "path": "docs/",
+        "description": "Replace docs/sample.md with your real corpus — drop .md, .txt, or (with pip install pypdf) .pdf files here, then run `python -m src.pipeline index` to rebuild the Chroma collection."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pip install -e .",
+      "cp .env.example .env",
+      "python -m src.pipeline index",
+      "python -m src.pipeline ask 'what is paged attention?'"
+    ],
+    "entrypoints": ["src/pipeline.py"],
+    "preview": null,
+    "extensionPoints": ["src/pipeline.py", "docs/"]
+  }
+}

package/registry/layers/framework/react-vite-ts/files/App.tsx

@@ -1,82 +1,19 @@
-import { Button } from '@/components/ui/button'
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
-import { Badge } from '@/components/ui/badge'
-
-const features = [
-  {
-    title: 'shadcn/ui Components',
-    description: '27 pre-installed components — Button, Card, Dialog, Table, and more. Import from @/components/ui/',
-    badge: 'Ready',
-  },
-  {
-    title: 'Tailwind CSS',
-    description: 'Utility-first styling with design tokens, dark mode support, and responsive breakpoints.',
-    badge: 'Configured',
-  },
-  {
-    title: 'TypeScript + Vite',
-    description: 'Fast builds with HMR. Path aliases configured — use @/ for src/ imports.',
-    badge: 'Fast',
-  },
-]
+// Minimal App skeleton. Replace the <main> contents with your product UI.
+// shadcn/ui components are pre-installed under @/components/ui/.
+// Path alias @/ → src/ is configured in vite.config.ts and tsconfig.json.
+// See AGENTS.md for the full component inventory and extension points.
 
 export default function App() {
   return (
     <div className="min-h-screen bg-background text-foreground">
-      <header className="border-b bg-card">
-        <div className="container mx-auto flex h-16 items-center justify-between px-4">
-          <div className="flex items-center gap-3">
-            <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-primary text-primary-foreground text-sm font-bold">
-              {'{{projectName}}'.charAt(0).toUpperCase()}
-            </div>
-            <span className="text-lg font-semibold">{'{{projectName}}'}</span>
-          </div>
-          <nav className="flex items-center gap-2">
-            <Button variant="ghost" size="sm">Documentation</Button>
-            <Button size="sm">Get Started</Button>
-          </nav>
+      <header className="border-b">
+        <div className="container mx-auto flex h-14 items-center px-4">
+          <span className="text-sm font-semibold">{'{{projectName}}'}</span>
         </div>
       </header>
-
-      <main className="container mx-auto px-4">
-        <section className="mx-auto max-w-3xl py-20 text-center">
-          <Badge variant="secondary" className="mb-4">Scaffold Ready</Badge>
-          <h1 className="text-5xl font-bold tracking-tight">{'{{headline}}'}</h1>
-          <p className="mx-auto mt-6 max-w-xl text-xl text-muted-foreground">
-            {'{{subheadline}}'}
-          </p>
-          <div className="mt-8 flex justify-center gap-4">
-            <Button size="lg">Read AGENTS.md</Button>
-            <Button size="lg" variant="outline">Browse Components</Button>
-          </div>
-        </section>
-
-        <section className="mx-auto max-w-4xl pb-20">
-          <div className="grid gap-6 md:grid-cols-3">
-            {features.map((feature) => (
-              <Card key={feature.title} className="relative overflow-hidden">
-                <CardHeader>
-                  <div className="flex items-center justify-between">
-                    <CardTitle className="text-lg">{feature.title}</CardTitle>
-                    <Badge variant="outline" className="text-xs">{feature.badge}</Badge>
-                  </div>
-                </CardHeader>
-                <CardContent>
-                  <CardDescription className="text-sm leading-relaxed">
-                    {feature.description}
-                  </CardDescription>
-                </CardContent>
-              </Card>
-            ))}
-          </div>
-        </section>
+      <main className="container mx-auto px-4 py-8">
+        {/* Build your UI here. */}
       </main>
-
-      <footer className="border-t py-8">
-        <div className="container mx-auto px-4 text-center text-sm text-muted-foreground">
-          Built with starter-foundry &middot; Read AGENTS.md to customize
-        </div>
-      </footer>
     </div>
   )
 }

package/registry/layers/framework/realtime-audio-ts/files/audio.ts

@@ -0,0 +1,75 @@
+// AudioGraph owns the AudioContext lifecycle. Construction is cheap
+// (no stream attached yet); unlock() is the autoplay-policy dance that
+// must run inside a user-gesture handler.
+
+const FFT_SIZE = 1024; // power of 2, 32..32768; sets analyser.frequencyBinCount = 512
+
+export class AudioGraph {
+  readonly context: AudioContext;
+  readonly analyser: AnalyserNode;
+  private readonly gainNode: GainNode;
+  private source: MediaStreamAudioSourceNode | null = null;
+  private currentStream: MediaStream | null = null;
+
+  constructor() {
+    // Construct-but-don't-resume. AudioContext starts suspended in
+    // Chrome/Safari until the user gesture handler calls resume().
+    this.context = new AudioContext();
+    this.analyser = this.context.createAnalyser();
+    this.analyser.fftSize = FFT_SIZE;
+    this.analyser.smoothingTimeConstant = 0.8;
+    this.gainNode = this.context.createGain();
+    this.gainNode.gain.value = 1;
+    this.gainNode.connect(this.analyser);
+  }
+
+  async unlock(): Promise<void> {
+    // Critical: must be called from a user-gesture handler, otherwise
+    // the AudioContext stays suspended and getByteFrequencyData returns
+    // all zeros with NO error. This is the #1 "audio doesn't work"
+    // gotcha in the browser audio stack.
+    if (this.context.state === "suspended") {
+      await this.context.resume();
+    }
+  }
+
+  async resumeIfSuspended(): Promise<void> {
+    // iOS Safari suspends the context on tab-background >30s. Call
+    // from a visibilitychange listener to recover automatically.
+    if (this.context.state === "suspended") {
+      try {
+        await this.context.resume();
+      } catch {
+        // If we're outside a user gesture, resume will reject silently.
+        // The next click on the Start button will unlock again.
+      }
+    }
+  }
+
+  attachStream(stream: MediaStream): void {
+    this.detachCurrent();
+    this.currentStream = stream;
+    this.source = this.context.createMediaStreamSource(stream);
+    this.source.connect(this.gainNode);
+  }
+
+  setGain(value: number): void {
+    // Clamp defensively — negative values invert the signal and values
+    // above ~3 clip on most playback chains.
+    const clamped = Math.max(0, Math.min(value, 3));
+    this.gainNode.gain.setTargetAtTime(clamped, this.context.currentTime, 0.01);
+  }
+
+  stop(): void {
+    this.detachCurrent();
+  }
+
+  private detachCurrent(): void {
+    this.source?.disconnect();
+    this.source = null;
+    if (this.currentStream) {
+      for (const track of this.currentStream.getTracks()) track.stop();
+      this.currentStream = null;
+    }
+  }
+}

package/registry/layers/framework/realtime-audio-ts/files/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{projectName}}</title>
+    <link rel="stylesheet" href="/src/styles.css" />
+  </head>
+  <body>
+    <main id="app">
+      <header>
+        <h1>{{headline}}</h1>
+        <p>{{subheadline}}</p>
+      </header>
+      <section class="controls">
+        <button id="start" type="button">Start microphone</button>
+        <button id="stop" type="button" disabled>Stop</button>
+        <label>
+          Gain
+          <input id="gain" type="range" min="0" max="2" step="0.01" value="1" />
+        </label>
+        <span id="status" class="status" data-state="idle">Idle</span>
+      </section>
+      <canvas id="visualizer" width="720" height="180"></canvas>
+      <section class="peer">
+        <h2>WebRTC peer</h2>
+        <p id="peer-status">Peer connection not initialized — see src/peer.ts to wire signalling.</p>
+        <!-- autoplay + playsinline required for iOS Safari; srcObject is set by main.ts when a remote track arrives -->
+        <audio id="remote-audio" autoplay playsinline></audio>
+      </section>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/registry/layers/framework/realtime-audio-ts/files/main.ts

@@ -0,0 +1,93 @@
+// Glue: Start button unlocks the AudioContext (autoplay policy), grabs
+// the mic stream, pipes it through the AudioGraph, attaches the
+// visualizer, and hands the stream to the WebRTC peer harness.
+//
+// No bundler-level abstraction here on purpose — each module owns one
+// concern and main.ts is the only place they meet.
+
+import { AudioGraph } from "./audio";
+import { Visualizer } from "./visualizer";
+import { createPeer, type Peer } from "./peer";
+
+const startButton = document.querySelector<HTMLButtonElement>("#start")!;
+const stopButton = document.querySelector<HTMLButtonElement>("#stop")!;
+const gainSlider = document.querySelector<HTMLInputElement>("#gain")!;
+const statusEl = document.querySelector<HTMLSpanElement>("#status")!;
+const canvas = document.querySelector<HTMLCanvasElement>("#visualizer")!;
+const peerStatusEl = document.querySelector<HTMLParagraphElement>("#peer-status")!;
+const remoteAudioEl = document.querySelector<HTMLAudioElement>("#remote-audio")!;
+
+const graph = new AudioGraph();
+const visualizer = new Visualizer(canvas);
+let activePeer: Peer | null = null;
+
+function setStatus(state: "idle" | "listening" | "error", label: string): void {
+  statusEl.dataset.state = state;
+  statusEl.textContent = label;
+}
+
+startButton.addEventListener("click", async () => {
+  startButton.disabled = true;
+  try {
+    // Autoplay unlock — must be inside the user-gesture handler. Safari
+    // and Chrome both refuse to run an AudioContext created outside of
+    // one.
+    await graph.unlock();
+
+    const stream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        echoCancellation: true,
+        noiseSuppression: true,
+        autoGainControl: true,
+      },
+      video: false,
+    });
+
+    graph.attachStream(stream);
+    visualizer.attach(graph.analyser);
+    activePeer = createPeer({
+      stream,
+      onRemoteTrack: (_track, streams) => {
+        // Wire the first remote stream to the <audio> element so incoming
+        // peer audio plays back. MediaStream assignment is idempotent.
+        const first = streams[0];
+        if (first && remoteAudioEl.srcObject !== first) {
+          remoteAudioEl.srcObject = first;
+        }
+      },
+      onStateChange: (state) => {
+        peerStatusEl.textContent = `Peer state: ${state}`;
+      },
+    });
+
+    stopButton.disabled = false;
+    setStatus("listening", "Listening");
+  } catch (error) {
+    setStatus("error", `Microphone denied: ${(error as Error).message}`);
+    startButton.disabled = false;
+  }
+});
+
+stopButton.addEventListener("click", () => {
+  visualizer.detach();
+  graph.stop();
+  activePeer?.close();
+  activePeer = null;
+  stopButton.disabled = true;
+  startButton.disabled = false;
+  setStatus("idle", "Idle");
+  peerStatusEl.textContent = "Peer closed.";
+  remoteAudioEl.srcObject = null;
+});
+
+gainSlider.addEventListener("input", () => {
+  graph.setGain(Number(gainSlider.value));
+});
+
+// Safari on iOS suspends the AudioContext when the page backgrounds.
+// Resume on return or the meters stay frozen forever.
+document.addEventListener("visibilitychange", () => {
+  if (document.visibilityState === "visible") {
+    graph.resumeIfSuspended();
+  }
+});

package/registry/layers/framework/realtime-audio-ts/files/peer.ts

@@ -0,0 +1,68 @@
+// Minimal WebRTC peer scaffold for realtime audio. Wires an RTCPeerConnection
+// with a placeholder signalling layer the product replaces with its own
+// transport (WebSocket, Socket.IO, Supabase realtime, etc).
+
+export interface PeerOptions {
+  stream: MediaStream
+  iceServers?: RTCIceServer[]
+  onRemoteTrack?: (track: MediaStreamTrack, streams: ReadonlyArray<MediaStream>) => void
+  onStateChange?: (state: RTCPeerConnectionState) => void
+}
+
+export interface Peer {
+  pc: RTCPeerConnection
+  createOffer: () => Promise<RTCSessionDescriptionInit>
+  acceptAnswer: (answer: RTCSessionDescriptionInit) => Promise<void>
+  acceptOffer: (offer: RTCSessionDescriptionInit) => Promise<RTCSessionDescriptionInit>
+  close: () => void
+}
+
+export function createPeer(opts: PeerOptions): Peer {
+  const pc = new RTCPeerConnection({
+    iceServers: opts.iceServers ?? [{ urls: 'stun:stun.l.google.com:19302' }],
+  })
+
+  // ICE candidates need to go over the SIGNALLING channel — the product
+  // attaches a handler on pc.onicecandidate and forwards to the peer.
+  pc.onicecandidate = (event) => {
+    if (event.candidate) {
+      // SIGNALLING TODO: send event.candidate.toJSON() to the remote peer.
+    }
+  }
+
+  pc.ontrack = (event) => {
+    if (opts.onRemoteTrack) opts.onRemoteTrack(event.track, event.streams)
+  }
+
+  pc.onconnectionstatechange = () => {
+    if (opts.onStateChange) opts.onStateChange(pc.connectionState)
+  }
+
+  // addTrack MUST happen BEFORE createOffer, otherwise the offer's SDP
+  // is missing the audio m-line and the remote peer has nothing to answer.
+  for (const track of opts.stream.getTracks()) {
+    pc.addTrack(track, opts.stream)
+  }
+
+  return {
+    pc,
+    async createOffer() {
+      const offer = await pc.createOffer()
+      await pc.setLocalDescription(offer)
+      return offer
+    },
+    async acceptAnswer(answer) {
+      await pc.setRemoteDescription(answer)
+    },
+    async acceptOffer(offer) {
+      await pc.setRemoteDescription(offer)
+      const answer = await pc.createAnswer()
+      await pc.setLocalDescription(answer)
+      return answer
+    },
+    close() {
+      pc.getSenders().forEach((s) => s.track?.stop())
+      pc.close()
+    },
+  }
+}