pool-anything 0.1.0 → 0.1.1

package/dist/cli/tui.js

@@ -0,0 +1,254 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Rich interactive shell built on Ink + React.
+ * Same command core as the plain frontend (commands.ts) — only rendering differs.
+ * `serve` exits the TUI first (Ink owns the screen) and boots the server after.
+ */
+import { useEffect, useRef, useState } from "react";
+import { Box, Text, render, useApp, useInput } from "ink";
+import { PROVIDERS, mask } from "../pool/index.js";
+import { HOST, PORT } from "../config/env.js";
+import { parse } from "./nl.js";
+import { fmtCompact, fmtFull } from "./ui.js";
+import { dispatch, insertKeys, liveStats, } from "./commands.js";
+export let serveRequested = false;
+let nextId = 1;
+function useTranscript() {
+    const [entries, setEntries] = useState([]);
+    const push = (node) => setEntries((prev) => [...prev.slice(-60), { id: nextId++, node }]);
+    const clear = () => setEntries([]);
+    return { entries, push, clear };
+}
+function Banner({ version }) {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "cyan", paddingX: 2, paddingY: 0, flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "cyan", children: ["pool-anything v", version, " \u2014 API key pooler"] }), _jsx(Text, { dimColor: true, children: "Type '.help' for commands, 'exit' to quit" })] }));
+}
+function PoolsView({ pools }) {
+    if (pools.length === 0) {
+        return _jsxs(Text, { dimColor: true, children: ["(no pools yet \u2014 try: create pool ", "<name>", " for ", "<provider>", ")"] });
+    }
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "cyan", paddingX: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: [pools.length, " active pool", pools.length === 1 ? "" : "s"] }), pools.map((p) => {
+                const usage = p.quota === null
+                    ? `${fmtCompact(p.used)} tokens`
+                    : `${fmtCompact(p.used)} / ${fmtCompact(p.quota * p.keys)} tokens`;
+                return (_jsxs(Text, { dimColor: !p.active, children: [_jsxs(Text, { color: "yellow", children: ["#", p.id] }), " ", _jsxs(Text, { bold: true, children: ["\"", p.name, "\""] }), " ", _jsxs(Text, { color: "cyan", children: ["(", p.provider, ")"] }), " \u2014 ", p.keys, " key", p.keys === 1 ? "" : "s", ",", " ", usage, p.active ? "" : ", inactive"] }, p.id));
+            })] }));
+}
+function ProvidersView() {
+    return (_jsx(Box, { flexDirection: "column", children: PROVIDERS.map((p) => (_jsxs(Text, { children: [_jsxs(Text, { color: "cyan", children: ["- ", p.id] }), " ", _jsxs(Text, { dimColor: true, children: ["\u2014 ", p.name, " (", p.quota || "no quota", ")"] })] }, p.id))) }));
+}
+function KeysView({ pool, keys }) {
+    if (keys.length === 0) {
+        return _jsxs(Text, { dimColor: true, children: ["Pool #", pool.id, " \"", pool.name, "\" has no keys. Try: add keys to ", pool.provider, "."] });
+    }
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, children: ["Keys in pool #", pool.id, " \"", pool.name, "\":"] }), keys.map((k) => (_jsxs(Text, { children: ["  ", _jsxs(Text, { color: "yellow", children: ["#", k.id] }), " ", k.label, " ", _jsxs(Text, { dimColor: true, children: ["(", k.masked, ")"] })] }, k.id))), _jsx(Text, { dimColor: true, children: "Keys are shown masked \u2014 raw values never print." })] }));
+}
+function QuotaBar({ used, total }) {
+    const width = 28;
+    const filled = total <= 0 ? 0 : Math.min(width, Math.round((used / total) * width));
+    return (_jsxs(Text, { children: [_jsx(Text, { color: "green", children: "█".repeat(filled) }), _jsx(Text, { dimColor: true, children: "░".repeat(width - filled) })] }));
+}
+function UsageView({ view, perKey }) {
+    const total = view.quota === null ? null : view.quota * view.keys;
+    const pct = total === null || total === 0 ? null : Math.round((view.used / total) * 100);
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "green", paddingX: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: ["Pool #", view.id, ": ", view.name, " ", _jsxs(Text, { color: "cyan", children: ["(", view.provider, ")"] })] }), _jsxs(Text, { children: ["Used: ", _jsx(Text, { bold: true, children: fmtFull(view.used) }), " tokens \u2502 Quota: ", total === null ? "unlimited" : fmtFull(total), " \u2502 Remaining:", " ", view.remaining === null ? "—" : fmtFull(view.remaining), pct !== null ? ` (${pct}% exhausted)` : ""] }), total !== null && _jsx(QuotaBar, { used: view.used, total: total }), _jsxs(Text, { children: ["Status: ", view.cooling > 0 ? _jsxs(Text, { color: "yellow", children: [view.cooling, " cooling"] }) : _jsx(Text, { color: "green", children: "OK" }), " \u2502 Keys:", " ", view.keys, " active, ", view.cooling, " cooling"] }), perKey.map((k) => (_jsxs(Text, { children: ["  ", k.label, " ", _jsxs(Text, { dimColor: true, children: ["(", k.masked, ")"] }), ": ", fmtFull(k.used), " tok"] }, k.label)))] }));
+}
+function MessageView({ tone, text }) {
+    const color = tone === "ok" ? "green" : tone === "err" ? "red" : undefined;
+    const prefix = tone === "ok" ? "✓ " : tone === "err" ? "✗ " : "";
+    return _jsxs(Text, { color: color, children: [prefix, text] });
+}
+function WatchView({ pool, onDone }) {
+    const [tick, setTick] = useState(0);
+    useEffect(() => {
+        const t = setInterval(() => setTick((n) => n + 1), 2000);
+        return () => clearInterval(t);
+    }, []);
+    useInput((_input, key) => {
+        if (key.escape || _input === "q" || _input === "Q")
+            onDone();
+    }, { isActive: true });
+    void tick;
+    const st = liveStats(pool.id);
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "yellow", paddingX: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: ["\uD83D\uDD04 Pool #", pool.id, " \"", pool.name, "\" \u2014 live usage ", _jsx(Text, { dimColor: true, children: "[auto-refresh 2s, press q to exit]" })] }), _jsxs(Text, { children: ["Requests: ", _jsxs(Text, { bold: true, color: "green", children: [st.reqMin, "/min"] }), " \u2502 Tokens: ", _jsxs(Text, { bold: true, color: "green", children: [st.tokMin, "/min"] }), " \u2502 Avg latency:", " ", st.avgLatency === null ? "—" : `${(st.avgLatency / 1000).toFixed(1)}s`] }), st.perKey.map((k) => (_jsxs(Text, { children: ["  ", k.label, " ", _jsxs(Text, { dimColor: true, children: ["(", mask(k.apiKey), ")"] }), ": ", fmtFull(k.used), " tok"] }, k.id)))] }));
+}
+function ResultView({ result }) {
+    switch (result.kind) {
+        case "message": return _jsx(MessageView, { tone: result.tone, text: result.text });
+        case "pools": return _jsx(PoolsView, { pools: result.pools });
+        case "providers": return _jsx(ProvidersView, {});
+        case "keys": return _jsx(KeysView, { pool: result.pool, keys: result.keys });
+        case "usage": return _jsx(UsageView, { view: result.view, perKey: result.perKey });
+        default: return null;
+    }
+}
+function Shell({ version }) {
+    const app = useApp();
+    const { entries, push, clear } = useTranscript();
+    const [input, setInput] = useState("");
+    const [history, setHistory] = useState([]);
+    const [histIdx, setHistIdx] = useState(-1);
+    const [mode, setMode] = useState({ t: "normal" });
+    const [collected, setCollected] = useState(0);
+    const importLines = useRef([]);
+    const questionResolve = useRef(null);
+    const ask = (q) => new Promise((resolve) => {
+        questionResolve.current = resolve;
+        setMode({ t: "question", prompt: q });
+    });
+    const submitImportLine = (line) => {
+        const st = mode;
+        if (st.t !== "import")
+            return;
+        if (line.trim() === "" || line.trim() === ".done" || line === "\x04") {
+            finishImport(st.pool);
+            return;
+        }
+        importLines.current.push(line);
+        setCollected(importLines.current.length);
+        if (st.expected !== null && importLines.current.length >= st.expected) {
+            finishImport(st.pool);
+        }
+    };
+    const finishImport = (pool) => {
+        const lines = importLines.current;
+        importLines.current = [];
+        setCollected(0);
+        setMode({ t: "normal" });
+        if (lines.length === 0) {
+            push(_jsx(MessageView, { tone: "info", text: "No keys pasted \u2014 nothing added." }));
+            return;
+        }
+        const { added, skipped } = insertKeys(pool, lines);
+        push(_jsx(MessageView, { tone: "ok", text: `Added ${added} key${added === 1 ? "" : "s"} to pool #${pool.id}${skipped > 0 ? ` (${skipped} skipped: blank/duplicate/invalid)` : ""}.` }));
+    };
+    const runCommand = async (cmd) => {
+        push(_jsxs(Text, { children: [_jsx(Text, { color: "yellow", bold: true, children: "\u276F " }), _jsx(Text, { bold: true, children: cmd })] }));
+        // `serve` boots a long-lived server that logs to stdout — exit the TUI
+        // first (Ink owns the screen), then start the server after unmount.
+        if (parse(cmd).kind === "serve") {
+            push(_jsx(MessageView, { tone: "ok", text: `Starting server on http://${HOST}:${PORT} …` }));
+            serveRequested = true;
+            app.exit();
+            return;
+        }
+        let r;
+        try {
+            r = await dispatch(cmd, ask);
+        }
+        catch (e) {
+            push(_jsx(MessageView, { tone: "err", text: `Error: ${e.message}` }));
+            return;
+        }
+        if (r.kind === "exit") {
+            app.exit();
+            return;
+        }
+        if (r.kind === "clear") {
+            clear();
+            return;
+        }
+        // A confirmed uninstall removes the binary — show the result, then leave
+        // the shell instead of prompting on a dead install.
+        if (parse(cmd).kind === "uninstall" && r.kind === "message" && r.tone === "ok") {
+            push(_jsx(ResultView, { result: r }));
+            app.exit();
+            return;
+        }
+        if (r.kind === "watch") {
+            setMode({ t: "watch", pool: r.pool });
+            return;
+        }
+        if (r.kind === "import") {
+            importLines.current = [];
+            setCollected(0);
+            setMode({ t: "import", pool: r.pool, expected: r.expected });
+            push(_jsx(MessageView, { tone: "ok", text: `Opening key import mode for "${r.pool.name}" (pool #${r.pool.id})` }));
+            push(_jsx(Text, { dimColor: true, children: r.hint }));
+            return;
+        }
+        if (r.kind === "serve") {
+            // Unreachable: serve is intercepted above so Ink unmounts before the
+            // server (which logs to stdout) starts. Kept for exhaustiveness.
+            push(_jsx(MessageView, { tone: "ok", text: `Server on http://${HOST}:${PORT}` }));
+            return;
+        }
+        push(_jsx(ResultView, { result: r }));
+    };
+    /** Submit one complete line from the prompt (shared by Return, pasted and cooked newlines). */
+    const submitLine = (line) => {
+        setInput("");
+        setHistIdx(-1);
+        if (mode.t === "question") {
+            const resolve = questionResolve.current;
+            questionResolve.current = null;
+            setMode({ t: "normal" });
+            push(_jsxs(Text, { dimColor: true, children: [mode.prompt, line] }));
+            resolve?.(line);
+            return;
+        }
+        if (mode.t === "import") {
+            submitImportLine(line);
+            return;
+        }
+        if (line.trim() === "")
+            return;
+        setHistory((h) => [...h.slice(-99), line]);
+        void runCommand(line);
+    };
+    useInput((ch, key) => {
+        if (mode.t === "watch")
+            return; // WatchView owns the keyboard.
+        if (ch === "\x04") {
+            // Ctrl+D: finish an import, or exit an empty prompt. (Before the
+            // ctrl guard: Ink reports ctrl+d with key.ctrl set.)
+            if (mode.t === "import")
+                submitImportLine(ch);
+            else if (input === "")
+                app.exit();
+            return;
+        }
+        if (ch && /[\r\n]/.test(ch)) {
+            // Return, pasted newlines, or cooked-mode line delivery: every
+            // complete segment is its own submit, the tail stays on the prompt.
+            const segments = (input + ch).split(/[\r\n]/);
+            const rest = segments.pop() ?? "";
+            for (const seg of segments)
+                submitLine(seg);
+            setInput(rest);
+            return;
+        }
+        if (key.upArrow || key.downArrow) {
+            if (history.length === 0)
+                return;
+            const next = key.upArrow
+                ? (histIdx === -1 ? history.length - 1 : Math.max(0, histIdx - 1))
+                : (histIdx === -1 ? -1 : Math.min(history.length - 1, histIdx + 1));
+            setHistIdx(next);
+            setInput(next === -1 ? "" : history[next]);
+            return;
+        }
+        if (key.backspace || key.delete) {
+            setInput((s) => s.slice(0, -1));
+            return;
+        }
+        if (key.ctrl && (ch === "u" || ch === "U")) {
+            setInput("");
+            return;
+        }
+        if (key.ctrl || key.meta || key.escape)
+            return;
+        if (ch)
+            setInput((s) => s + ch);
+    });
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Banner, { version: version }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: entries.map((e) => (_jsx(Box, { marginBottom: 0, children: e.node }, e.id))) }), mode.t === "watch" ? (_jsx(Box, { marginTop: 1, children: _jsx(WatchView, { pool: mode.pool, onDone: () => { setMode({ t: "normal" }); push(_jsx(Text, { dimColor: true, children: "Stopped watching." })); } }) })) : (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: mode.t === "import" ? "cyan" : "yellow", bold: true, children: mode.t === "import" ? "... " : mode.t === "question" ? "" : "❯ " }), mode.t === "question" ? (_jsxs(Text, { children: [mode.prompt, _jsx(Text, { bold: true, children: input }), _jsx(Text, { inverse: true, children: " " })] })) : (_jsxs(Text, { children: [_jsx(Text, { bold: true, children: input }), _jsx(Text, { inverse: true, children: " " })] }))] })), mode.t === "import" && (_jsxs(Text, { dimColor: true, children: [collected, " collected \u2014 empty line or Ctrl+D to finish"] }))] }));
+}
+export async function startTui(version) {
+    const { waitUntilExit } = render(_jsx(Shell, { version: version }));
+    await waitUntilExit();
+    if (serveRequested) {
+        serveRequested = false;
+        await import("../server.js");
+        return;
+    }
+    console.log("Goodbye!");
+}

package/dist/cli/ui.js

@@ -68,6 +68,8 @@ export function helpBox() {
         ["next [for <pool>]", "rotate: show the next key (masked)"],
         ["consume <n> [on <pool>]", "record token usage"],
         ["serve", "start the web UI + API server"],
+        ["update", "check npm and upgrade to the latest version"],
+        ["uninstall", "remove the global CLI (asks to confirm, CLI only)"],
         ["clear", "clear the screen"],
         ["exit", "quit"],
     ];

package/dist/cli.js

@@ -33,7 +33,8 @@ Usage:
 Assistant commands (also inside the shell): list pools, list providers,
   list keys [for <pool>], show usage for <pool>, add [N] keys to <pool>,
   create pool <name> for <provider>, delete pool <name>, watch <pool>,
-  next [for <pool>], consume <n> [on <pool>], serve, exit. Type '.help' in-shell.
+  next [for <pool>], consume <n> [on <pool>], update, uninstall (CLI only),
+  serve, exit. Type '.help' in-shell.
 
 Options (server):
   -p, --port <n>      Port for the web UI + API (default: 3000, or $PORT)
@@ -192,8 +193,15 @@ if (!opts.serve && oneShot) {
     process.exit(await execOnce(oneShot));
 }
 if (!opts.serve && process.stdin.isTTY && process.stdout.isTTY) {
-    const { startRepl } = await import("./cli/repl.js");
-    await startRepl(version);
+    try {
+        const { startTui } = await import("./cli/tui.js");
+        await startTui(version);
+    }
+    catch (e) {
+        console.error(`[warn] rich shell unavailable (${e.message}), falling back to plain mode.`);
+        const { startRepl } = await import("./cli/repl.js");
+        await startRepl(version);
+    }
     process.exit(0);
 }
 await import("./server.js");

package/dist/data/providers.json

@@ -13,7 +13,7 @@
   {"id":"perplexity","name":"Perplexity","baseUrl":"https://api.perplexity.ai","keyHeader":"Authorization","keyPrefix":"Bearer ","extraHeaders":{},"quota":"$5 credit on signup","docsUrl":"https://docs.perplexity.ai/getting-started/quickstart","keyFields":["api_key"],"hint":"perplexity.ai/settings/api, pplx-…","logo":"public/logos/perplexity.svg"},
   {"id":"anyscale","name":"Anyscale Endpoints","baseUrl":"https://api.endpoints.anyscale.com/v1","keyHeader":"Authorization","keyPrefix":"Bearer ","extraHeaders":{},"quota":"legacy, deprecated","docsUrl":"https://docs.anyscale.com/endpoints/overview","keyFields":["api_key"],"hint":"app.endpoints.anyscale.com/credentials","logo":"public/logos/anyscale.svg"},
   {"id":"elevenlabs","name":"ElevenLabs","baseUrl":"https://api.elevenlabs.io/v1","keyHeader":"xi-api-key","keyPrefix":"","extraHeaders":{},"quota":"10k credits/mo free","docsUrl":"https://elevenlabs.io/docs","keyFields":["api_key"],"hint":"elevenlabs.io API key","logo":"public/logos/elevenlabs.svg"},
-  {"id":"deepgram","name":"Deepgram","baseUrl":"https://api.deepgram.com/v1","keyHeader":"Authorization","keyPrefix":"Token ","extraHeaders":{},"quota":"$200 credit on signup","docsUrl":"https://developers.deepgram.com/docs","keyFields":["api_key"],"hint":"Authorization: Token …","logo":"public/logos/deepgram.svg"},
+  {"id":"deepgram","name":"Deepgram","baseUrl":"https://api.deepgram.com","keyHeader":"Authorization","keyPrefix":"Token ","extraHeaders":{},"quota":"$200 credit on signup","docsUrl":"https://developers.deepgram.com/docs","keyFields":["api_key"],"hint":"Authorization: Token …","logo":"public/logos/deepgram.svg"},
   {"id":"cartesia","name":"Cartesia","baseUrl":"https://api.cartesia.ai","keyHeader":"X-API-Key","keyPrefix":"","extraHeaders":{"Cartesia-Version":"2024-06-10"},"quota":"20,000 free tokens","docsUrl":"https://docs.cartesia.ai","keyFields":["api_key"],"hint":"Paste a Cartesia API key","logo":"public/logos/cartesia.svg"},
   {"id":"tavily","name":"Tavily","baseUrl":"https://api.tavily.com","keyHeader":"Authorization","keyPrefix":"Bearer ","extraHeaders":{},"quota":"1,000 credits/mo free","docsUrl":"https://docs.tavily.com/documentation/api-reference/endpoint/search","keyFields":["api_key"],"hint":"app.tavily.com/home, tvly-…","logo":"public/logos/tavily.svg"},
   {"id":"brave-search","name":"Brave Search","baseUrl":"https://api.search.brave.com/res/v1","keyHeader":"X-Subscription-Token","keyPrefix":"","extraHeaders":{},"quota":"2,000 queries/mo free","docsUrl":"https://brave.com/search/api/","keyFields":["api_key"],"hint":"brave.com/search/api/","logo":"public/logos/brave.svg"},

package/dist/playground/adapters.js

@@ -0,0 +1,304 @@
+// Playground provider adapters — single source of truth for how the admin
+// Playground talks to each provider through the key-pool proxy.
+//
+// The proxy forwards {path, method, headers?, body?, query?, form?} to
+// baseUrl + path with auth injected server-side, so each adapter only needs:
+// which path to hit, which body shape to send, and where to find the output.
+// Placeholders in templates: <<MODEL>> <<TEXT>> <<QUERY>> <<VOICE>> <<SIZE>>
+// <<ORG>> <<SID>> <<DOMAIN>>. Filled client-side (see playgroundPage).
+//
+// Researched against official docs (2026) in 6 parallel batches; keep this
+// table in sync with data/providers.json — every provider id must appear.
+export const ADAPTERS = {
+    groq: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: true, audioIn: true, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "openai/gpt-oss-20b" },
+        notes: "temperature 0 becomes 1e-8; vision model-dependent.",
+    },
+    openrouter: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: true, audioIn: false, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "meta-llama/llama-3.3-70b-instruct" },
+        notes: "Router passthrough; vision model-dependent.",
+    },
+    mistral: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: true, audioIn: false, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "mistral-small-latest" },
+        notes: "Vision via image_url on capable models.",
+    },
+    cohere: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: false, audioIn: false, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "command-a-plus-05-2026" },
+        notes: "Compatibility API; no image_url on compat endpoint.",
+    },
+    fireworks: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: true, audioIn: false,
+        image: { path: "/images/generations", body: { model: "<<MODEL>>", prompt: "<<TEXT>>", n: 1 } },
+        audio: null, video: null, probe: null,
+        defaults: { chat: "accounts/fireworks/models/llama-v3p1-8b-instruct", image: "accounts/fireworks/models/flux-1-schnell" },
+        notes: "Model ids are full accounts/fireworks/models/... paths.",
+    },
+    together: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: true, audioIn: false,
+        image: { path: "/images/generations", body: { model: "<<MODEL>>", prompt: "<<TEXT>>", n: 1 } },
+        audio: null, video: null, probe: null,
+        defaults: { chat: "Qwen/Qwen3.5-9B", image: "FLUX.1-schnell" },
+        notes: "Namespaced model ids (org/Model).",
+    },
+    huggingface: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: true, audioIn: false,
+        image: { path: "/images/generations", body: { model: "<<MODEL>>", prompt: "<<TEXT>>", n: 1 } },
+        audio: null, video: null, probe: null,
+        defaults: { chat: "openai/gpt-oss-120b", image: "black-forest-labs/FLUX.1-schnell" },
+        notes: "Inference Providers router; chat-only + images.",
+    },
+    openai: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: true, audioIn: true,
+        image: { path: "/images/generations", body: { model: "<<MODEL>>", prompt: "<<TEXT>>", n: 1 } },
+        audio: { path: "/audio/speech", body: { model: "<<MODEL>>", input: "<<TEXT>>", voice: "<<VOICE>>" } },
+        video: null, probe: null, voiceDefault: "alloy",
+        defaults: { chat: "gpt-4o-mini", image: "gpt-image-1", audio: "gpt-4o-mini-tts" },
+        notes: "TTS returns binary audio, not JSON.",
+    },
+    perplexity: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai",
+        textPaths: ["choices.0.message.content", "citations", "search_results"],
+        vision: true, audioIn: false, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "sonar-pro" },
+        notes: "/chat/completions aliases the Sonar API.",
+    },
+    anyscale: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: false, audioIn: false, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "meta-llama/Llama-3.1-70B-Instruct" },
+        notes: "Model ids rotate; auto-list via GET /models.",
+    },
+    custom: {
+        kind: "openai-chat", chatPath: "/chat/completions", chatStyle: "openai",
+        modelsPath: "/models", modelsStyle: "openai", textPaths: ["choices.0.message.content"],
+        vision: true, audioIn: false, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "gpt-4o-mini" },
+        notes: "Generic OpenAI-chat default for user baseUrl.",
+    },
+    anthropic: {
+        kind: "native-chat", chatPath: "/messages", chatStyle: "anthropic",
+        modelsPath: null, textPaths: ["content.0.text"],
+        vision: true, audioIn: false, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "claude-sonnet-5" },
+        notes: "Body {model,max_tokens,messages[,system]}; version header injected server-side.",
+    },
+    gemini: {
+        kind: "native-chat", chatPath: "/models/<<MODEL>>:generateContent", chatStyle: "gemini",
+        modelsPath: "/models", modelsStyle: "gemini", textPaths: ["candidates.0.content.parts.0.text"],
+        vision: true, audioIn: true, videoIn: true, image: null, audio: null, video: null, probe: null,
+        defaults: { chat: "gemini-3.8-flash" },
+        notes: "Model embedded in path; key via x-goog-api-key header.",
+    },
+    replicate: {
+        kind: "image", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["output", "output.0"],
+        vision: false, audioIn: false,
+        image: { path: "/models/black-forest-labs/flux-schnell/predictions", body: { input: { prompt: "<<TEXT>>" } } },
+        audio: null, video: null, probe: null,
+        defaults: { image: "black-forest-labs/flux-schnell" },
+        notes: "Async: POST returns {id,status}; poll GET /predictions/{id} until succeeded.",
+    },
+    elevenlabs: {
+        kind: "tts", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: [],
+        vision: false, audioIn: false, image: null,
+        audio: { path: "/text-to-speech/<<VOICE>>", body: { text: "<<TEXT>>", model_id: "<<MODEL>>" } },
+        video: null, probe: null, voiceDefault: "JBFqnCBsd6RMkjVDRZzb",
+        defaults: { audio: "eleven_multilingual_v2" },
+        notes: "Returns binary audio; voice id in path.",
+    },
+    cartesia: {
+        kind: "tts", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: [],
+        vision: false, audioIn: false, image: null,
+        audio: { path: "/tts/bytes", body: { model_id: "<<MODEL>>", transcript: "<<TEXT>>", voice: { mode: "id", id: "<<VOICE>>" }, output_format: { container: "mp3", sample_rate: 44100, bit_rate: 128000 } } },
+        video: null, probe: null, voiceDefault: "09f6bad8-2340-4eac-89ec-74885c34d189",
+        defaults: { audio: "sonic-3.6" },
+        notes: "Returns binary audio; Cartesia-Version header injected server-side.",
+    },
+    deepgram: {
+        kind: "tts", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["results.channels.0.alternatives.0.transcript"],
+        vision: false, audioIn: true, image: null,
+        audio: { path: "/v1/speak", altPath: "/v2/speak", altMatch: "flux", query: { model: "<<MODEL>>" }, body: { text: "<<TEXT>>" } },
+        video: null, probe: null,
+        defaults: { audio: "aura-2-thalia-en" },
+        notes: "TTS model is a query param, returns binary audio. Paths carry the version explicitly because the base URL is the host root (so /v2/speak resolves correctly). Flux-variant models route to /v2/speak, which requires a flux- voice model. STT: POST /v1/listen (not wired).",
+    },
+    tavily: {
+        kind: "search", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["answer", "results.0.content", "results.0.url", "results.0.title"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/search", method: "POST", body: { query: "<<QUERY>>", topic: "<<TOPIC>>", time_range: "<<TIME_RANGE>>", max_results: "<<MAX_RESULTS>>", include_answer: "<<ANSWER>>", chunks_per_source: "<<CHUNKS>>", auto_parameters: "<<AUTO>>", include_domains: "<<INCL_DOMAINS>>", exclude_domains: "<<EXCL_DOMAINS>>", search_depth: "<<DEPTH>>" } },
+        defaults: {},
+        notes: "Search-only; siblings /extract /crawl /map.",
+    },
+    "brave-search": {
+        kind: "search", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["web.results.0.title", "web.results.0.url", "web.results.0.description"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/web/search", method: "GET", query: { q: "<<QUERY>>", count: "5" } },
+        defaults: {},
+        notes: "Token header injected server-side.",
+    },
+    serper: {
+        kind: "search", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["organic.0.title", "organic.0.link", "organic.0.snippet"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/search", method: "POST", query: {}, body: { q: "<<QUERY>>" } },
+        defaults: {},
+        notes: "Response also carries knowledgeGraph/answerBox.",
+    },
+    scrapingbee: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["$"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/", method: "GET", query: { url: "<<QUERY>>", render_js: "false" } },
+        defaults: {},
+        notes: "Returns raw HTML, not JSON; api_key injected server-side as query param.",
+    },
+    finnhub: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["c", "pc", "d", "dp"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/quote", method: "GET", query: { symbol: "<<QUERY>>" } },
+        defaults: {},
+        notes: "Query is a stock symbol, e.g. AAPL.",
+    },
+    mapbox: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["features.0.place_name", "features.0.center"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/geocoding/v5/mapbox.places/<<QUERY>>.json", method: "GET", query: { limit: "5" } },
+        defaults: {},
+        notes: "access_token injected server-side as query param.",
+    },
+    googlemaps: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["status", "results.0.formatted_address", "results.0.geometry.location"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/geocode/json", method: "GET", query: { address: "<<QUERY>>" } },
+        defaults: {},
+        notes: "key injected server-side as query param.",
+    },
+    resend: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["id"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/emails", method: "POST", body: { from: "test@example.com", to: ["to@example.com"], subject: "<<TEXT>>", text: "<<TEXT>>" } },
+        defaults: {},
+        notes: "Sends a real email; 200 returns {id}.",
+    },
+    sendgrid: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: [],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/mail/send", method: "POST", body: { personalizations: [{ to: [{ email: "to@example.com" }] }], from: { email: "test@example.com" }, subject: "<<TEXT>>", content: [{ type: "text/plain", value: "<<TEXT>>" }] } },
+        defaults: {},
+        notes: "Sends a real email; success is 202 with empty body.",
+    },
+    mailgun: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["id", "message"],
+        vision: false, audioIn: false, image: null, audio: null, video: null, formOnly: true,
+        probe: { path: "/<<DOMAIN>>/messages", method: "POST", body: { from: "test@example.com", to: "to@example.com", subject: "<<TEXT>>", text: "<<TEXT>>" } },
+        defaults: {},
+        notes: "Form-only upstream; proxy sends form. <<DOMAIN>> is your mailgun domain.",
+    },
+    postmark: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["MessageID"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/email", method: "POST", body: { From: "test@example.com", To: "to@example.com", Subject: "<<TEXT>>", TextBody: "<<TEXT>>", MessageStream: "outbound" } },
+        defaults: {},
+        notes: "Sends a real email; 200 returns {MessageID,...}.",
+    },
+    twilio: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["sid", "status", "uri"],
+        vision: false, audioIn: false, image: null, audio: null, video: null, formOnly: true,
+        probe: { path: "/Accounts/<<SID>>/Messages.json", method: "POST", body: { To: "+15558675310", From: "+15557122661", Body: "<<TEXT>>" } },
+        defaults: {},
+        notes: "Form-only upstream; proxy sends form. <<SID>> is your Account SID.",
+    },
+    openweather: {
+        kind: "search", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["name", "main.temp", "weather"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/weather", method: "GET", query: { q: "<<QUERY>>", units: "metric" } },
+        defaults: {},
+        notes: "appid injected server-side as query param; query is a city name.",
+    },
+    supabase: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["0"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/tablename", method: "GET", query: { select: "*" } },
+        defaults: {},
+        notes: "PostgREST; replace tablename. Per-project URL resolved per key.",
+    },
+    neon: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["projects", "projects.0.id"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/projects", method: "GET", query: {} },
+        defaults: {},
+        notes: "Response {projects:[...]}.",
+    },
+    upstash: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["0", "0.database_id"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/redis/databases", method: "GET", query: {} },
+        defaults: {},
+        notes: "Bare array of Database objects.",
+    },
+    turso: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["databases", "databases.0.Name", "databases.0.DbId"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/organizations/<<ORG>>/databases", method: "GET", query: {} },
+        defaults: {},
+        notes: "<<ORG>> is your organization slug.",
+    },
+    appwrite: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["databases", "databases.0.$id", "total"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/databases", method: "GET", query: {} },
+        defaults: {},
+        notes: "Project header injected server-side; endpoint resolved per key.",
+    },
+    cloudflare: {
+        kind: "rest", chatPath: null, chatStyle: null,
+        modelsPath: null, textPaths: ["result", "result.0.id", "result_info", "success"],
+        vision: false, audioIn: false, image: null, audio: null, video: null,
+        probe: { path: "/zones", method: "GET", query: { per_page: "5" } },
+        defaults: {},
+        notes: "Envelope {success,result[],result_info}.",
+    },
+};
+/** Placeholder tokens filled client-side from playground inputs. */
+export const PLACEHOLDERS = ["<<MODEL>>", "<<TEXT>>", "<<QUERY>>", "<<VOICE>>", "<<SIZE>>", "<<ORG>>", "<<SID>>", "<<DOMAIN>>"];