@tangle-network/starter-foundry 0.5.4 → 0.7.2

package/registry/families/kyc-onboarding/manifest.json

@@ -0,0 +1,140 @@
+{
+  "id": "kyc-onboarding",
+  "description": "kyc-onboarding starter — derived from 5× real demand signal. Taxonomy guess: typescript/node/frontend.",
+  "tags": [
+    "node",
+    "frontend",
+    "typescript"
+  ],
+  "taxonomy": {
+    "language": "typescript",
+    "runtime": "node",
+    "surface": "frontend"
+  },
+  "defaults": {
+    "projectType": "frontend",
+    "serviceName": "starter-foundry-kyc-onboarding"
+  },
+  "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/src/main.tsx",
+      "target": "src/main.tsx"
+    },
+    {
+      "source": "files/README.md",
+      "target": "README.md"
+    },
+    {
+      "source": "files/validate-node.mjs",
+      "target": "validate-node.mjs"
+    },
+    {
+      "source": "files/src/App.tsx",
+      "target": "src/App.tsx"
+    },
+    {
+      "source": "files/.env.example",
+      "target": ".env.example"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "package.json"
+    },
+    {
+      "type": "file-exists",
+      "path": "tsconfig.json"
+    },
+    {
+      "type": "file-exists",
+      "path": "vite.config.ts"
+    }
+  ],
+  "contextHints": {
+    "commands": [
+      "Initialize a new project with the kyc-onboarding starter",
+      "Install required dependencies",
+      "Configure KYC onboarding workflow"
+    ],
+    "entrypoints": [
+      "index.ts"
+    ],
+    "preview": null,
+    "extensionPoints": []
+  },
+  "keywords": [
+    "kyc",
+    "kyc onboarding",
+    "identity verification",
+    "document verification",
+    "liveness check",
+    "aml compliance",
+    "sumsub",
+    "persona identity",
+    "passkey onboarding",
+    "know your customer"
+  ],
+  "tieredKeywords": {
+    "tier1": [
+      "kyc",
+      "kyc onboarding",
+      "identity verification",
+      "document verification",
+      "liveness check"
+    ],
+    "tier2": [
+      "aml compliance",
+      "sumsub",
+      "persona identity",
+      "passkey onboarding",
+      "know your customer"
+    ]
+  },
+  "buildHints": {
+    "whenToUse": "Use the kyc-onboarding starter when building applications that require Know Your Customer (KYC) onboarding processes, particularly those that involve frontend interactions and require a robust TypeScript and Node.js backend.",
+    "firstSteps": [
+      "Initialize a new project with the kyc-onboarding starter",
+      "Install required dependencies",
+      "Configure KYC onboarding workflow",
+      "Implement frontend components for user interaction",
+      "Set up backend API for KYC verification"
+    ],
+    "gotchas": [
+      "Ensure compliance with regulatory requirements for KYC",
+      "Handle sensitive user data securely",
+      "Implement robust error handling and logging",
+      "Optimize performance for large user bases",
+      "Keep dependencies up to date for security patches"
+    ],
+    "architectureNotes": [
+      "Modularize KYC onboarding process into separate components",
+      "Use a service-oriented architecture for scalability",
+      "Implement caching for frequently accessed data",
+      "Use WebSockets for real-time updates",
+      "Monitor performance and adjust architecture as needed"
+    ],
+    "placeholders": [
+      {
+        "path": "index.ts",
+        "description": "Primary entrypoint agents must extend."
+      }
+    ]
+  }
+}

package/registry/families/legal-case-mgmt/files/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch --experimental-strip-types src/server.ts",
+    "start": "node --experimental-strip-types src/server.ts",
+    "validate": "node validate-legal.mjs",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.36.0",
+    "postgres": "^3.4.5",
+    "decimal.js": "^10.4.3"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.30.0",
+    "typescript": "^5.9.0",
+    "@types/node": "^20.17.0"
+  },
+  "overrides": { "vite": "^6.4.2" },
+  "pnpm": { "overrides": { "vite": "^6.4.2" } }
+}

package/registry/families/legal-case-mgmt/files/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/registry/families/legal-case-mgmt/files/validate-legal.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(join(here, 'package.json'), 'utf8'))
+if (!pkg.dependencies?.['drizzle-orm']) throw new Error('drizzle-orm missing from dependencies')
+for (const rel of ['tsconfig.json', 'src/db/schema.ts']) {
+  if (!existsSync(join(here, rel))) throw new Error(`missing ${rel}`)
+}
+console.log('legal case mgmt starter ok')

package/registry/families/legal-case-mgmt/manifest.json

@@ -0,0 +1,85 @@
+{
+  "id": "legal-case-mgmt",
+  "description": "Legal practice management API — matters, parties, documents, time entries, billing rates, invoice generation from time entries.",
+  "tags": [
+    "legal",
+    "case-management",
+    "api",
+    "typescript"
+  ],
+  "taxonomy": {
+    "language": "typescript",
+    "runtime": "node",
+    "surface": "api"
+  },
+  "slots": {
+    "database": {
+      "options": ["database:sqlite", "database:postgres"],
+      "default": "database:postgres"
+    },
+    "auth": {
+      "options": ["auth:none", "auth:better-auth", "auth:clerk"],
+      "default": "auth:better-auth"
+    }
+  },
+  "defaults": {
+    "projectType": "api",
+    "serviceName": "starter-foundry-legal",
+    "port": 8102,
+    "databaseProvider": "postgres"
+  },
+  "files": [
+    { "source": "files/package.json", "target": "package.json" },
+    { "source": "files/tsconfig.json", "target": "tsconfig.json" },
+    { "source": "files/validate-legal.mjs", "target": "validate-legal.mjs" }
+  ],
+  "validationChecks": [
+    { "type": "file-exists", "path": "src/server.ts" },
+    { "type": "file-exists", "path": "src/db/schema.ts" },
+    { "type": "file-exists", "path": "src/api/matter.ts" },
+    { "type": "file-exists", "path": "src/api/billing.ts" },
+    {
+      "type": "command-success",
+      "command": ["node", "validate-legal.mjs"],
+      "expect": "legal starter ok"
+    }
+  ],
+  "contextHints": {
+    "commands": ["pnpm install", "pnpm dev", "pnpm drizzle-kit generate", "pnpm drizzle-kit migrate"],
+    "entrypoints": ["src/server.ts", "src/db/schema.ts", "src/api/matter.ts", "src/api/billing.ts"],
+    "preview": { "path": "/health" },
+    "extensionPoints": ["src/db/schema.ts", "src/api/"]
+  },
+  "keywords": [
+    "legal tech",
+    "legaltech",
+    "case management",
+    "law practice",
+    "matter management",
+    "legal billing",
+    "attorney timekeeping",
+    "law firm software",
+    "legal saas",
+    "practice management"
+  ],
+  "scoring": {
+    "boost": {
+      "legal": 3,
+      "law": 3
+    }
+  },
+  "tieredKeywords": {
+    "tier1": [
+      "legal tech",
+      "legaltech",
+      "case management",
+      "law practice",
+      "matter management",
+      "legal billing",
+      "attorney timekeeping",
+      "law firm software",
+      "practice management"
+    ],
+    "tier2": ["legal saas", "billable hours", "trust accounting"]
+  }
+}

package/registry/families/livekit-sfu/files/.env.example

@@ -0,0 +1,8 @@
+# Copy to .env and replace both values. Secret must be ≥32 bytes. The same
+# pair lives in livekit.yaml under `keys:` — keep them in sync.
+LIVEKIT_API_KEY={{livekitApiKey}}
+LIVEKIT_API_SECRET={{livekitApiSecret}}
+LIVEKIT_WS_URL=ws://localhost:{{port}}
+
+# Control-plane HTTP port (the token-minting Express server in src/server.ts).
+CONTROL_PORT={{controlPort}}

package/registry/families/livekit-sfu/files/docker-compose.yml

@@ -0,0 +1,27 @@
+services:
+  livekit:
+    image: livekit/livekit-server:latest
+    restart: unless-stopped
+    command: ["--config", "/etc/livekit.yaml"]
+    network_mode: host
+    # Host networking is required so the SFU can advertise its real port range
+    # (UDP 50000-60000 by default) to WebRTC clients without NAT rewriting.
+    volumes:
+      - ./livekit.yaml:/etc/livekit.yaml:ro
+    depends_on:
+      - redis
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    # Used for multi-node room state coordination. A single-node deployment
+    # works without Redis, but keeping it in compose means scaling to N SFUs
+    # is a `docker compose up --scale livekit=N` away.
+    ports:
+      - "127.0.0.1:6379:6379"
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis-data:/data
+
+volumes:
+  redis-data:

package/registry/families/livekit-sfu/files/livekit.yaml

@@ -0,0 +1,30 @@
+# LiveKit SFU config. Values here are read once at server startup.
+# See https://docs.livekit.io/home/self-hosting/deployment/ for full reference.
+
+port: {{port}}
+bind_addresses:
+  - ""
+
+rtc:
+  # Client-facing UDP/TCP for ICE candidates.
+  tcp_port: 7881
+  port_range_start: 50000
+  port_range_end: 60000
+  # Auto-discover the external IP via STUN. In production, set use_external_ip
+  # to false and hardcode node_ip to the public address — STUN discovery
+  # fails inside some Kubernetes/overlay-net setups.
+  use_external_ip: true
+
+redis:
+  address: 127.0.0.1:6379
+
+# API keys → secrets for signing JWT access tokens. Secret must be ≥32 bytes.
+# Rotate by adding a new key; old keys keep minting valid tokens until all
+# clients have migrated. Replace both values before deploying.
+keys:
+  {{livekitApiKey}}: "{{livekitApiSecret}}"
+
+# Production logging: json format so Loki/Datadog/CloudWatch parse it cleanly.
+logging:
+  level: info
+  json: true

package/registry/families/livekit-sfu/files/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "node --import tsx src/server.ts",
+    "sfu:up": "docker compose up -d",
+    "sfu:down": "docker compose down",
+    "sfu:logs": "docker compose logs -f livekit",
+    "validate": "node validate-livekit.mjs"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "livekit-server-sdk": "^2.9.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.17.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.0"
+  },
+  "overrides": {
+    "vite": "^6.4.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "^6.4.2"
+    }
+  }
+}

package/registry/families/livekit-sfu/files/tsconfig.json

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

package/registry/families/livekit-sfu/files/validate-livekit.mjs

@@ -0,0 +1,46 @@
+// Structural validator for livekit-sfu. Does NOT start docker or the SFU
+// (scaffold validation runs without Docker available); confirms entry files
+// exist, cross-reference each other, and configs are syntactically valid.
+
+import fs from "node:fs/promises";
+
+const [pkgSource, serverSource, composeSource, livekitYaml] = await Promise.all([
+  fs.readFile("package.json", "utf8"),
+  fs.readFile("src/server.ts", "utf8"),
+  fs.readFile("docker-compose.yml", "utf8"),
+  fs.readFile("livekit.yaml", "utf8"),
+]);
+
+const pkg = JSON.parse(pkgSource);
+if (pkg.name !== "{{packageName}}") {
+  throw new Error(`package.json name should be "{{packageName}}", got "${pkg.name}"`);
+}
+if (!pkg.dependencies?.["livekit-server-sdk"]) {
+  throw new Error("package.json missing livekit-server-sdk dependency");
+}
+
+if (!serverSource.includes("AccessToken")) {
+  throw new Error("src/server.ts must mint livekit AccessToken JWTs");
+}
+if (!serverSource.includes("/token")) {
+  throw new Error("src/server.ts must expose a POST /token route");
+}
+if (!serverSource.includes('"/health"') && !serverSource.includes("'/health'")) {
+  throw new Error("src/server.ts missing /health route contract");
+}
+
+if (!composeSource.includes("livekit/livekit-server")) {
+  throw new Error("docker-compose.yml must reference livekit/livekit-server image");
+}
+if (!composeSource.includes("redis")) {
+  throw new Error("docker-compose.yml must include the redis sidecar for multi-node coordination");
+}
+
+if (!livekitYaml.includes("keys:")) {
+  throw new Error("livekit.yaml must declare at least one API key/secret pair under 'keys:'");
+}
+if (!livekitYaml.includes("use_external_ip")) {
+  throw new Error("livekit.yaml must set rtc.use_external_ip — WebRTC won't work without it");
+}
+
+console.log("livekit-sfu starter ok");

package/registry/families/livekit-sfu/manifest.json

@@ -0,0 +1,152 @@
+{
+  "id": "livekit-sfu",
+  "description": "Self-hosted LiveKit SFU for realtime audio/video rooms. docker-compose ships livekit-server + Redis; Node control plane mints JWT access tokens so clients can join rooms with per-identity grants.",
+  "tags": [
+    "webrtc",
+    "sfu",
+    "livekit",
+    "realtime",
+    "media",
+    "typescript",
+    "docker"
+  ],
+  "taxonomy": {
+    "language": "typescript",
+    "runtime": "node",
+    "surface": "api"
+  },
+  "defaults": {
+    "projectType": "api",
+    "serviceName": "starter-foundry-livekit",
+    "port": 7880,
+    "controlPort": 8098,
+    "livekitApiKey": "devkey",
+    "livekitApiSecret": "devsecret-change-me-32-bytes-min"
+  },
+  "files": [
+    {
+      "source": "files/package.json",
+      "target": "package.json"
+    },
+    {
+      "source": "files/tsconfig.json",
+      "target": "tsconfig.json"
+    },
+    {
+      "source": "files/docker-compose.yml",
+      "target": "docker-compose.yml"
+    },
+    {
+      "source": "files/livekit.yaml",
+      "target": "livekit.yaml"
+    },
+    {
+      "source": "files/validate-livekit.mjs",
+      "target": "validate-livekit.mjs"
+    },
+    {
+      "source": "files/.env.example",
+      "target": ".env.example"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "src/server.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "livekit.yaml"
+    },
+    {
+      "type": "file-exists",
+      "path": "docker-compose.yml"
+    },
+    {
+      "type": "command-success",
+      "command": [
+        "node",
+        "validate-livekit.mjs"
+      ],
+      "expect": "livekit-sfu starter ok"
+    }
+  ],
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "docker compose up -d",
+      "pnpm run dev",
+      "curl -X POST http://localhost:{{controlPort}}/token -H 'Content-Type: application/json' -d '{\"room\":\"demo\",\"identity\":\"alice\"}'"
+    ],
+    "entrypoints": [
+      "src/server.ts",
+      "livekit.yaml",
+      "docker-compose.yml",
+      "package.json"
+    ],
+    "preview": {
+      "path": "/health"
+    },
+    "extensionPoints": [
+      "livekit.yaml",
+      "src/server.ts",
+      ".env"
+    ]
+  },
+  "keywords": [
+    "livekit sfu",
+    "livekit server",
+    "webrtc sfu",
+    "self-hosted webrtc",
+    "video conferencing server",
+    "realtime audio room",
+    "selective forwarding unit",
+    "sfu server",
+    "webrtc room",
+    "video room server",
+    "self-hosted livekit"
+  ],
+  "scoring": {
+    "boost": {
+      "livekit sfu": 4,
+      "webrtc sfu": 4,
+      "selective forwarding unit": 4,
+      "self-hosted livekit": 3
+    }
+  },
+  "tieredKeywords": {
+    "tier1": [
+      "livekit sfu",
+      "webrtc sfu",
+      "selective forwarding unit",
+      "self-hosted livekit",
+      "livekit server self-hosted"
+    ],
+    "tier2": [
+      "self-hosted webrtc",
+      "video conferencing server",
+      "realtime audio room server",
+      "sfu server",
+      "video room server"
+    ],
+    "archetypes": [
+      "self-hosted zoom",
+      "open source meet",
+      "multi-party video call",
+      "webinar platform",
+      "live audio room",
+      "clubhouse clone",
+      "twitter spaces clone",
+      "group voice chat server"
+    ]
+  },
+  "buildHints": {
+    "gotchas": [
+      "getUserMedia requires HTTPS outside localhost — clients won't be able to publish tracks from a plain-HTTP domain on any browser.",
+      "LiveKit SFU needs the public egress IP visible to clients. In docker-compose, set rtc.use_external_ip: true; behind NAT, pre-configure rtc.node_ip and open UDP 7881 + TCP 7881 fallback.",
+      "Access tokens expire — the control plane mints short-lived JWTs (default TTL 6h). Clients must re-request before expiry or the SFU refuses the WS upgrade.",
+      "Redis is only required for multi-node deployments. Single-node works without it; docker-compose still ships Redis so scale-out is a compose-scale away.",
+      "API key + secret in livekit.yaml must stay ≥32 bytes. Shorter secrets are rejected at startup with a cryptic 'HMAC key too short' error."
+    ]
+  }
+}

package/registry/families/lora-training/files/.env.example

@@ -0,0 +1,8 @@
+# Required for gated base models (Llama, Mistral, Gemma). Get one at
+# https://huggingface.co/settings/tokens (read scope is enough). You must
+# ALSO click "accept license" on the model's Hub page — token alone 403s.
+HUGGING_FACE_HUB_TOKEN=
+
+# Optional: W&B logging. Set report_to: 'wandb' in config/train.yaml to enable.
+WANDB_API_KEY=
+WANDB_PROJECT=lora-training

package/registry/families/lora-training/files/README-lora.md

@@ -0,0 +1,71 @@
+# LoRA / QLoRA training — operator guide
+
+4-bit QLoRA fine-tuning on top of a HuggingFace base model, driven by
+TRL's `SFTTrainer` and PEFT.
+
+```
+data/sample.jsonl  ──►  tokenizer  ──►  4-bit base (frozen)
+                                        + LoRA adapters (trained)
+                                              │
+                                              ▼
+                                      outputs/lora-adapter/
+```
+
+## First-run
+
+```bash
+pip install -e .
+cp .env.example .env        # set HUGGING_FACE_HUB_TOKEN for gated bases
+# Optional on A100+/H100: install flash-attn and flip attn_implementation
+# to 'flash_attention_2' in config/train.yaml.
+
+# Drop your real dataset in:
+cat > data/train.jsonl <<'EOF'
+{"messages": [{"role":"user","content":"..."}, {"role":"assistant","content":"..."}]}
+...
+EOF
+# Point config/train.yaml:data.path at it.
+
+python train.py --config config/train.yaml
+# Checkpoints + adapter land in outputs/lora-adapter/
+python infer.py --adapter outputs/lora-adapter --prompt "hello"
+```
+
+## What you get
+
+- **QLoRA by default** — base model loads in 4-bit NF4, adapters train in bf16.
+  A 7-8B base fits on 16-24GB VRAM; a 70B base fits on one 80GB GPU.
+- **target_modules preset** for Llama/Mistral architectures. Gemma/Phi need
+  a different list — read the base model's `config.json` and match the
+  linear projection names.
+- **SFTTrainer** handles the ChatML / Llama chat template automatically when
+  the dataset uses a `messages` column. Swap to `text` for raw-text SFT.
+- **Paged AdamW 8-bit** optimizer — saves ~4GB of optimizer state vs fp32 Adam.
+- **Gradient checkpointing** on — trades ~20% throughput for ~30% less activation memory.
+
+## Serving the trained adapter
+
+```python
+# Single adapter: PEFT wrapper directly
+from peft import PeftModel
+from transformers import AutoModelForCausalLM
+base = AutoModelForCausalLM.from_pretrained(BASE, torch_dtype=torch.bfloat16)
+model = PeftModel.from_pretrained(base, "./outputs/lora-adapter")
+
+# Multi-adapter serving: vLLM --enable-lora
+# vllm serve BASE --enable-lora \
+#     --lora-modules my-adapter=./outputs/lora-adapter
+```
+
+## Production notes
+
+- **Don't commit merged models** (14GB+). Commit / publish the adapter folder;
+  anyone with the base model can load it.
+- **W&B / TensorBoard** — set `report_to: 'wandb'` in `config/train.yaml` to
+  track loss/grad-norm/lr. Without a tracker you're training blind.
+- **Eval before serving** — shipping a LoRA without an eval set is how you
+  regress a working base model. Add a held-out set + a basic accuracy check.
+- **Rank sweeps**: r in {8, 16, 32, 64} is the useful range. Higher r helps
+  for broader task shifts, hurts on narrow ones (overfit risk).
+- **Mixing architectures**: every base family needs its own `target_modules`.
+  Llama ≠ Mistral ≠ Gemma ≠ Phi here.