@tangle-network/starter-foundry 0.5.3 → 0.7.0

package/registry/layers/framework/lora-training/files/train.py

@@ -0,0 +1,174 @@
+"""QLoRA training entrypoint.
+
+    python train.py --config config/train.yaml
+
+Loads a 4-bit-quantized base model, attaches PEFT LoRA adapters on the
+configured target_modules, and trains via TRL's SFTTrainer on a JSONL
+dataset with a `messages` column. Checkpoints land in training.output_dir.
+
+Requires TRL >= 0.12 (uses SFTConfig + processing_class API).
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any, Callable
+
+import torch
+import yaml
+from datasets import load_dataset
+from dotenv import load_dotenv
+from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
+from transformers import (
+    AutoModelForCausalLM,
+    AutoTokenizer,
+    BitsAndBytesConfig,
+)
+from trl import SFTConfig, SFTTrainer
+
+load_dotenv()
+
+
+def _load_config(path: Path) -> dict[str, Any]:
+    with open(path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def _dtype(name: str) -> torch.dtype:
+    return {
+        "bfloat16": torch.bfloat16,
+        "float16": torch.float16,
+        "float32": torch.float32,
+    }[name]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", type=Path, required=True, help="Path to train.yaml")
+    args = parser.parse_args()
+
+    cfg = _load_config(args.config)
+    model_cfg = cfg["model"]
+    lora_cfg = cfg["lora"]
+    data_cfg = cfg["data"]
+    train_cfg = cfg["training"]
+
+    # --- Tokenizer ------------------------------------------------------
+    tokenizer = AutoTokenizer.from_pretrained(
+        model_cfg["base_model_id"],
+        trust_remote_code=True,
+    )
+    if tokenizer.pad_token is None:
+        # Many causal LMs ship without a pad token; reusing eos is the
+        # standard workaround for SFT.
+        tokenizer.pad_token = tokenizer.eos_token
+
+    # --- Base model (4-bit QLoRA) --------------------------------------
+    bnb_config = None
+    if model_cfg.get("load_in_4bit", True):
+        bnb_config = BitsAndBytesConfig(
+            load_in_4bit=True,
+            bnb_4bit_quant_type=model_cfg.get("bnb_4bit_quant_type", "nf4"),
+            bnb_4bit_compute_dtype=_dtype(model_cfg.get("bnb_4bit_compute_dtype", "bfloat16")),
+            bnb_4bit_use_double_quant=model_cfg.get("bnb_4bit_use_double_quant", True),
+        )
+
+    model = AutoModelForCausalLM.from_pretrained(
+        model_cfg["base_model_id"],
+        quantization_config=bnb_config,
+        torch_dtype=_dtype(model_cfg.get("bnb_4bit_compute_dtype", "bfloat16")),
+        attn_implementation=model_cfg.get("attn_implementation", "sdpa"),
+        trust_remote_code=True,
+    )
+    model.config.use_cache = False  # incompatible with gradient checkpointing
+
+    if bnb_config is not None:
+        model = prepare_model_for_kbit_training(
+            model,
+            use_gradient_checkpointing=train_cfg.get("gradient_checkpointing", True),
+        )
+
+    # --- LoRA adapters --------------------------------------------------
+    peft_config = LoraConfig(
+        r=lora_cfg["r"],
+        lora_alpha=lora_cfg["alpha"],
+        lora_dropout=lora_cfg.get("dropout", 0.05),
+        bias=lora_cfg.get("bias", "none"),
+        task_type=lora_cfg.get("task_type", "CAUSAL_LM"),
+        target_modules=lora_cfg["target_modules"],
+    )
+    model = get_peft_model(model, peft_config)
+    trainable, total = 0, 0
+    for p in model.parameters():
+        total += p.numel()
+        if p.requires_grad:
+            trainable += p.numel()
+    print(f"trainable params: {trainable:,} / {total:,} ({100 * trainable / total:.4f}%)")
+
+    # --- Dataset --------------------------------------------------------
+    dataset = load_dataset("json", data_files=data_cfg["path"], split="train")
+    messages_col = data_cfg.get("messages_column", "messages")
+    text_col = data_cfg.get("text_column")
+
+    formatting_func: Callable[[dict[str, Any]], str] | None = None
+    # SFTConfig requires a non-None dataset_text_field; "text" is the
+    # conventional fallback when formatting_func drives the pipeline instead.
+    dataset_text_field: str = "text"
+
+    if text_col and text_col in dataset.column_names:
+        dataset_text_field = text_col
+    elif messages_col in dataset.column_names:
+        def _format(example: dict[str, Any]) -> str:
+            return tokenizer.apply_chat_template(  # type: ignore[return-value]
+                example[messages_col],
+                tokenize=False,
+                add_generation_prompt=False,
+            )
+        formatting_func = _format
+    else:
+        raise ValueError(
+            f"Dataset at {data_cfg['path']} has no '{messages_col}' or 'text' column"
+        )
+
+    # --- Training config (TRL >= 0.12 SFTConfig) ------------------------
+    sft_cfg = SFTConfig(
+        output_dir=train_cfg["output_dir"],
+        num_train_epochs=train_cfg["num_train_epochs"],
+        per_device_train_batch_size=train_cfg["per_device_train_batch_size"],
+        gradient_accumulation_steps=train_cfg["gradient_accumulation_steps"],
+        learning_rate=train_cfg["learning_rate"],
+        lr_scheduler_type=train_cfg.get("lr_scheduler_type", "cosine"),
+        warmup_ratio=train_cfg.get("warmup_ratio", 0.03),
+        weight_decay=train_cfg.get("weight_decay", 0.0),
+        optim=train_cfg.get("optim", "paged_adamw_8bit"),
+        logging_steps=train_cfg.get("logging_steps", 5),
+        save_steps=train_cfg.get("save_steps", 50),
+        save_total_limit=train_cfg.get("save_total_limit", 3),
+        bf16=train_cfg.get("bf16", True),
+        gradient_checkpointing=train_cfg.get("gradient_checkpointing", True),
+        report_to=train_cfg.get("report_to", "none"),
+        seed=train_cfg.get("seed", 42),
+        # SFT-specific params (moved out of SFTTrainer.__init__ in TRL 0.12)
+        max_seq_length=data_cfg.get("max_seq_length", 2048),
+        packing=False,
+        dataset_text_field=dataset_text_field,
+    )
+
+    trainer = SFTTrainer(
+        model=model,
+        args=sft_cfg,
+        train_dataset=dataset,
+        processing_class=tokenizer,  # replaces deprecated tokenizer= kwarg
+        formatting_func=formatting_func,
+    )
+
+    trainer.train()
+    trainer.save_model(train_cfg["output_dir"])
+    tokenizer.save_pretrained(train_cfg["output_dir"])
+    print(f"adapter saved to {train_cfg['output_dir']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/registry/layers/framework/lora-training/manifest.json

@@ -0,0 +1,78 @@
+{
+  "id": "lora-training",
+  "description": "Framework layer for lora-training — ships train.py (TRL SFTTrainer + PEFT + bitsandbytes) and infer.py (base + adapter). QLoRA 4-bit fine-tunes a 7B-8B model on a single 24 GB GPU; adapter checkpoints are 10-500 MB instead of 14+ GB for a merged model.",
+  "appliesTo": ["lora-training"],
+  "files": [
+    {
+      "source": "files/train.py",
+      "target": "train.py"
+    },
+    {
+      "source": "files/infer.py",
+      "target": "infer.py"
+    },
+    {
+      "source": "files/pyrightconfig.json",
+      "target": "pyrightconfig.json"
+    }
+  ],
+  "buildHints": {
+    "whenToUse": "Pick this when you need custom model behaviour (domain language, instruction style, task-specific format) but cannot or will not run full fine-tuning. QLoRA 4-bit lets a 7B-8B model tune on a single 24 GB GPU; 70B on a single 80 GB GPU. For pure inference without training, use vllm-server or ollama-server. For RAG-style grounding without training, use rag-pipeline-py.",
+    "firstSteps": [
+      "pip install -e .  — installs peft, transformers, bitsandbytes, trl>=0.12, accelerate, datasets",
+      "Replace data/sample.jsonl with your real training set (each line: {\"messages\": [{\"role\": ..., \"content\": ...}, ...]})",
+      "Edit config/train.yaml — set base_model_id, lora_r/alpha, epochs, learning_rate, and target_modules for your architecture",
+      "Set HUGGING_FACE_HUB_TOKEN in .env for gated base models (Llama, Mistral, Gemma)",
+      "python train.py --config config/train.yaml  — checkpoints land in training.output_dir",
+      "python infer.py --adapter ./outputs/lora-adapter --prompt 'test'  — smoke-test the adapter"
+    ],
+    "gotchas": [
+      "bitsandbytes 4-bit requires CUDA. There is no working CPU path for QLoRA — on a Mac it silently falls back to fp16 and OOMs.",
+      "LoRA target_modules is model-architecture-specific. Llama/Mistral use ['q_proj','k_proj','v_proj','o_proj','gate_proj','up_proj','down_proj']; Gemma and Phi differ. The wrong list means training runs but the adapter learns nothing.",
+      "lora_r above 64 stops helping and starts overfitting. Keep lora_alpha = 2 * lora_r (the standard ratio) so the effective learning rate stays stable across rank changes.",
+      "Checkpoint sizes: LoRA adapters are 10-500 MB; fully merged models are 14-30 GB. Commit the adapter directory only — never commit merged weights.",
+      "Gated base models need HUGGING_FACE_HUB_TOKEN *and* licence acceptance on the Hub — the token alone returns 403.",
+      "TRL SFTTrainer expects either a `text` column or a `messages` column. Mixing schemas in one file silently trains on the wrong field.",
+      "flash-attention-2 requires torch >= 2.1 and SM >= 8.0 GPU (A100/H100). On older GPUs set attn_implementation: 'sdpa' in config/train.yaml."
+    ],
+    "architectureNotes": [
+      "train.py is config-driven: all hyperparameters live in config/train.yaml; the script itself requires no edits for most runs.",
+      "infer.py reads the base model id from adapter_config.json (written by PEFT at save time), then falls back to config/train.yaml — no hardcoded model paths.",
+      "The formatting pipeline in train.py auto-detects whether the dataset has a 'messages' column (applies chat template) or a 'text' column (passes raw text to SFTTrainer)."
+    ],
+    "placeholders": [
+      {
+        "path": "data/sample.jsonl",
+        "description": "Replace with the real training set. Each line must be valid JSON with a 'messages' array (or a 'text' string for raw-text SFT)."
+      },
+      {
+        "path": "config/train.yaml",
+        "description": "Set base_model_id to your chosen base model, tune lora_r/lora_alpha, set target_modules for your architecture, and adjust epochs/learning_rate."
+      },
+      {
+        "path": ".env",
+        "description": "Add HUGGING_FACE_HUB_TOKEN=hf_... for gated base models (Llama 3, Mistral, Gemma). Leave empty for open models."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pip install -e .",
+      "python train.py --config config/train.yaml",
+      "python infer.py --adapter ./outputs/lora-adapter --prompt 'hello'",
+      "python infer.py --adapter ./outputs/lora-adapter --prompt 'hello' --no-4bit"
+    ],
+    "entrypoints": [
+      "train.py",
+      "infer.py",
+      "config/train.yaml",
+      "data/sample.jsonl"
+    ],
+    "preview": null,
+    "extensionPoints": [
+      "config/train.yaml",
+      "data/sample.jsonl",
+      "train.py"
+    ]
+  }
+}

package/registry/layers/framework/move-package/files/Move.toml

@@ -2,5 +2,24 @@
 name = "{{projectName}}"
 version = "0.0.1"
 
+# Named address for module paths. `package` is a Move-valid identifier
+# regardless of the project name (projectName may contain hyphens — which
+# are legal in Cargo/npm package names but illegal in Move identifiers).
+# Users can rename `package` to anything Move-identifier-safe; then update
+# `module package::...` references in sources/.
 [addresses]
-{{projectName}} = "_"
+package = "_"
+
+# Dev addresses resolve the `_` placeholder during `aptos move compile --dev`
+# and `aptos move test --dev`. Real on-chain deploys pass --named-addresses
+# on the CLI (see scripts/publish.sh in your toolchain). 0xcafe is the
+# convention-standard Aptos dev placeholder.
+[dev-addresses]
+package = "0xcafe"
+
+# AptosFramework provides std (signer, vector, string, ...) and the
+# aptos_framework namespace (coin, account, event, timestamp). Pinned to
+# `mainnet` branch so the resolved versions match what's actually deployed.
+# First `aptos move compile` fetches this git dep (~30s cold, cached after).
+[dependencies]
+AptosFramework = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-framework", rev = "mainnet" }

package/registry/layers/framework/move-package/files/module.move

@@ -1,4 +1,4 @@
-module {{projectName}}::{{moduleName}} {
+module package::{{moduleName}} {
     use std::signer;
 
     struct Treasury has key {

package/registry/layers/framework/move-package/files/test.move

@@ -1,9 +1,7 @@
-module {{projectName}}::{{moduleName}}Tests {
-    use {{projectName}}::{{moduleName}};
-
-    #[test(account = @{{projectName}})]
+module package::{{moduleName}}Tests {
+    #[test(account = @package)]
     fun initializes_balance(account: signer) {
-        {{moduleName}}::initialize(&account);
-        assert!({{moduleName}}::balance(@{{projectName}}) == 0, 0);
+        package::{{moduleName}}::initialize(&account);
+        assert!(package::{{moduleName}}::balance(@package) == 0, 0);
     }
 }

package/registry/layers/framework/multimodal-agent/files/App.tsx

@@ -0,0 +1,219 @@
+// Three-modality composer.
+//
+// Text, image, and audio are three independent state machines intentionally
+// kept in separate useState hooks so a change in one never stomps the
+// others. The Send handler is the only place they converge — it packs
+// whatever is currently present into a single FormData and POSTs it.
+
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+
+type SendState = 'idle' | 'sending'
+
+export default function App() {
+  const [text, setText] = useState('')
+  const [image, setImage] = useState<File | null>(null)
+  const [imagePreview, setImagePreview] = useState<string | null>(null)
+  const [audio, setAudio] = useState<Blob | null>(null)
+  const [audioPreview, setAudioPreview] = useState<string | null>(null)
+  const [recording, setRecording] = useState(false)
+  const [dragActive, setDragActive] = useState(false)
+  const [sendState, setSendState] = useState<SendState>('idle')
+  const [out, setOut] = useState('Drop an image, record 3 seconds of audio, type your question.')
+
+  const mediaRef = useRef<MediaRecorder | null>(null)
+  const streamRef = useRef<MediaStream | null>(null)
+  const chunksRef = useRef<Blob[]>([])
+
+  // Previews are ObjectURLs — revoke on replacement AND on unmount or
+  // Chrome silently retains the blob until a full GC cycle.
+  useEffect(() => () => {
+    if (imagePreview) URL.revokeObjectURL(imagePreview)
+  }, [imagePreview])
+  useEffect(() => () => {
+    if (audioPreview) URL.revokeObjectURL(audioPreview)
+  }, [audioPreview])
+
+  // On unmount, kill any live mic stream. React 19 StrictMode double-invokes
+  // effects in dev, so this also catches the "recording started, effect
+  // re-ran" race.
+  useEffect(() => () => {
+    streamRef.current?.getTracks().forEach((t) => t.stop())
+  }, [])
+
+  function assignImage(file: File | null) {
+    if (imagePreview) URL.revokeObjectURL(imagePreview)
+    setImage(file)
+    setImagePreview(file ? URL.createObjectURL(file) : null)
+  }
+
+  function onDrop(e: React.DragEvent<HTMLDivElement>) {
+    e.preventDefault()
+    setDragActive(false)
+    // Must read files synchronously — Safari clears dataTransfer once the
+    // handler returns, even if you await inside it.
+    const file = e.dataTransfer.files[0]
+    if (file && file.type.startsWith('image/')) assignImage(file)
+  }
+
+  function onDragOver(e: React.DragEvent<HTMLDivElement>) {
+    // preventDefault here is MANDATORY — without it the browser navigates
+    // away to the file URL and the drop event never fires.
+    e.preventDefault()
+    setDragActive(true)
+  }
+
+  function onDragLeave(e: React.DragEvent<HTMLDivElement>) {
+    e.preventDefault()
+    setDragActive(false)
+  }
+
+  async function startRecord() {
+    if (recording) return
+    try {
+      streamRef.current = await navigator.mediaDevices.getUserMedia({ audio: true })
+    } catch (err) {
+      setOut(`mic denied: ${err instanceof Error ? err.message : String(err)}`)
+      return
+    }
+    const mime =
+      ['audio/webm;codecs=opus', 'audio/webm', 'audio/mp4'].find((m) => MediaRecorder.isTypeSupported(m)) ?? ''
+    chunksRef.current = []
+    mediaRef.current = new MediaRecorder(streamRef.current, mime ? { mimeType: mime } : undefined)
+    mediaRef.current.ondataavailable = (ev) => {
+      if (ev.data.size > 0) chunksRef.current.push(ev.data)
+    }
+    mediaRef.current.onstop = () => {
+      const blob = new Blob(chunksRef.current, { type: mediaRef.current?.mimeType ?? 'audio/webm' })
+      if (audioPreview) URL.revokeObjectURL(audioPreview)
+      setAudio(blob)
+      setAudioPreview(URL.createObjectURL(blob))
+      streamRef.current?.getTracks().forEach((t) => t.stop())
+      streamRef.current = null
+    }
+    mediaRef.current.start()
+    setRecording(true)
+  }
+
+  function stopRecord() {
+    mediaRef.current?.state === 'recording' && mediaRef.current.stop()
+    setRecording(false)
+  }
+
+  const clearAudio = useCallback(() => {
+    if (audioPreview) URL.revokeObjectURL(audioPreview)
+    setAudio(null)
+    setAudioPreview(null)
+  }, [audioPreview])
+
+  async function send() {
+    if (sendState === 'sending') return
+    if (!text && !image && !audio) {
+      setOut('add at least one of: text, image, audio.')
+      return
+    }
+    setSendState('sending')
+    setOut('sending…')
+    try {
+      const form = new FormData()
+      form.set('text', text)
+      if (image) form.set('image', image, image.name)
+      if (audio) form.set('audio', audio, `clip.${(audio.type.split('/')[1] ?? 'webm').split(';')[0]}`)
+
+      const res = await fetch('/api/multimodal', { method: 'POST', body: form })
+      if (!res.ok) throw new Error(`multimodal failed: ${res.status}`)
+
+      // Handle both non-streamed JSON and streamed NDJSON transparently.
+      const contentType = res.headers.get('content-type') ?? ''
+      if (contentType.includes('application/json')) {
+        const { reply } = (await res.json()) as { reply: string }
+        setOut(reply)
+      } else {
+        const reader = res.body?.getReader()
+        if (!reader) {
+          setOut(await res.text())
+        } else {
+          const decoder = new TextDecoder()
+          let acc = ''
+          setOut('')
+          // Stream loop — flush each chunk straight to the output pre
+          // element so users see tokens as they arrive.
+          for (;;) {
+            const { value, done } = await reader.read()
+            if (done) break
+            acc += decoder.decode(value, { stream: true })
+            setOut(acc)
+          }
+        }
+      }
+    } catch (err) {
+      setOut(`error: ${err instanceof Error ? err.message : String(err)}`)
+    } finally {
+      setSendState('idle')
+    }
+  }
+
+  return (
+    <>
+      <h1>{'{{headline}}'}</h1>
+      <p className="sub">{'{{subheadline}}'}</p>
+
+      <div className="panels">
+        <section className="panel">
+          <h3>Text</h3>
+          <textarea
+            value={text}
+            onChange={(e) => setText(e.target.value)}
+            placeholder="Type your question. Empty is fine if image/audio is enough."
+          />
+        </section>
+
+        <section className="panel">
+          <h3>Image</h3>
+          <div
+            className={`drop ${dragActive ? 'active' : ''}`}
+            onDrop={onDrop}
+            onDragOver={onDragOver}
+            onDragLeave={onDragLeave}
+            onClick={() => document.getElementById('file-pick')?.click()}
+          >
+            {imagePreview ? <img src={imagePreview} alt="" /> : 'Drop or click to choose an image'}
+          </div>
+          <input
+            id="file-pick"
+            type="file"
+            accept="image/*"
+            hidden
+            onChange={(e) => assignImage(e.target.files?.[0] ?? null)}
+          />
+          {image && (
+            <button className="danger" onClick={() => assignImage(null)}>
+              Remove
+            </button>
+          )}
+        </section>
+
+        <section className="panel">
+          <h3>Audio</h3>
+          {!audio && (
+            <button onClick={recording ? stopRecord : startRecord}>
+              {recording ? <span className="recording">Stop recording</span> : 'Start recording'}
+            </button>
+          )}
+          {audioPreview && <audio src={audioPreview} controls />}
+          {audio && (
+            <button className="danger" onClick={clearAudio}>
+              Re-record
+            </button>
+          )}
+          {!audio && !recording && <span className="pill">webm/opus preferred</span>}
+        </section>
+      </div>
+
+      <button className="send" onClick={send} disabled={sendState === 'sending'}>
+        {sendState === 'sending' ? 'Thinking…' : 'Send all three'}
+      </button>
+
+      <pre id="out">{out}</pre>
+    </>
+  )
+}

package/registry/layers/framework/multimodal-agent/files/main.tsx

@@ -0,0 +1,12 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+const root = document.getElementById('root')
+if (!root) throw new Error('missing #root mount')
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/registry/layers/framework/multimodal-agent/manifest.json

@@ -0,0 +1,60 @@
+{
+  "id": "multimodal-agent",
+  "description": "React 19 multimodal composer — three independent inputs (text, image drop, audio record) packed into one multipart POST to /api/multimodal.",
+  "appliesTo": ["multimodal-agent"],
+  "files": [
+    {
+      "source": "files/main.tsx",
+      "target": "src/main.tsx"
+    },
+    {
+      "source": "files/App.tsx",
+      "target": "src/App.tsx"
+    }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "react": "^19.2.0",
+      "react-dom": "^19.2.0"
+    },
+    "devDependencies": {
+      "@types/react": "^19.2.0",
+      "@types/react-dom": "^19.2.0",
+      "@vitejs/plugin-react": "^4.7.0",
+      "typescript": "^5.9.0",
+      "vite": "^6.4.2"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Multimodal LLM clients that accept text, image, and audio in one request — GPT-4o, Claude Vision, or Gemini multimodal.",
+    "firstSteps": [
+      "Run `pnpm install` then `pnpm dev` — the three-panel composer loads on port 4182.",
+      "Wire the backend: implement POST /api/multimodal that accepts multipart/form-data with fields `text`, `image`, and `audio`. See api/README.md for provider recipes (Anthropic, OpenAI, Gemini).",
+      "The client handles both non-streamed JSON `{\"reply\":\"...\"}` and streamed text/plain — pick whichever the backend returns.",
+      "Run `node validate-multimodal.mjs` to verify the scaffold wiring before adding features."
+    ],
+    "gotchas": [
+      "multipart/form-data is the only format all three big multimodal APIs accept without re-encoding. Don't wrap image + audio in a JSON body — base64 overhead bloats payloads and breaks streaming.",
+      "React 19 Strict Mode runs effects twice in dev — getUserMedia without a cleanup track-stop causes NotReadableError on the second invocation. The cleanup is already wired; don't remove it.",
+      "Dropped files trigger both `dragover` and `drop` — preventDefault on dragover is MANDATORY or the browser navigates to the file URL and the drop handler never fires.",
+      "Safari's DataTransferItemList only exposes files synchronously inside the drop handler. Awaiting anything before reading `e.dataTransfer.files` clears the list.",
+      "The <audio> preview element needs `URL.revokeObjectURL` on re-record or remove — Chrome retains the blob until full GC otherwise."
+    ],
+    "architectureNotes": [
+      "Three independent useState machines (text, image, audio) converge only at send() — this prevents stale-closure bugs that arise from a single merged state object.",
+      "Streaming is plain Fetch API ReadableStream + TextDecoder — no SSE or WebSocket dependency required."
+    ],
+    "placeholders": [
+      {
+        "path": "src/App.tsx",
+        "description": "{{headline}} and {{subheadline}} are template tokens replaced at compose time by the family defaults. The POST target /api/multimodal is the fixed contract — implement that route in your backend."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": ["pnpm install", "pnpm dev", "pnpm build", "node validate-multimodal.mjs"],
+    "entrypoints": ["src/App.tsx", "src/main.tsx", "api/README.md"],
+    "preview": { "path": "/" },
+    "extensionPoints": ["src/App.tsx", "api/"]
+  }
+}

package/registry/layers/framework/observable-notebook/files/data/rows.json.ts

@@ -0,0 +1,11 @@
+interface Row {
+  month: number
+  revenue: number
+}
+
+const rows: Row[] = Array.from({ length: 12 }, (_, i) => ({
+  month: i + 1,
+  revenue: Math.round(10_000 + Math.sin(i / 2) * 3_000 + i * 200),
+}))
+
+process.stdout.write(JSON.stringify(rows))

package/registry/layers/framework/observable-notebook/files/overview.md

@@ -0,0 +1,28 @@
+---
+title: Overview
+---
+
+# Overview
+
+Data is loaded at build time from `src/data/rows.json.ts` and rendered
+reactively. The loader runs as a Node.js script; Observable Framework ships
+only the serialised output to the browser.
+
+```js
+const rows = await FileAttachment("data/rows.json").json();
+```
+
+```js
+Inputs.table(rows)
+```
+
+```js
+Plot.plot({
+  y: { grid: true, label: "Revenue ($)" },
+  marks: [Plot.barY(rows, { x: "month", y: "revenue", fill: "#2563eb" })]
+})
+```
+
+To use real data, replace the generated array in `src/data/rows.json.ts`
+with a database query or API fetch — the `FileAttachment` import above
+stays the same.

package/registry/layers/framework/observable-notebook/files/src/observablehq.d.ts

@@ -0,0 +1,12 @@
+declare module '@observablehq/framework' {
+  export interface Config {
+    title?: string;
+    pages?: Array<{ name: string; path: string }>;
+    theme?: string | string[];
+    root?: string;
+    output?: string;
+    search?: boolean;
+    [key: string]: unknown;
+  }
+  export function defineConfig(config: Config): Config;
+}

package/registry/layers/framework/observable-notebook/files/tsconfig.json

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