@xberg-io/opencode-liter-llm 2.1.2 → 2.2.0

package/.opencode/ai-rulez-bundle.json

@@ -0,0 +1,43 @@
+{
+  "mcp": {
+    "liter-llm": {
+      "type": "local",
+      "command": [
+        "${PLUGIN_ROOT}/scripts/mcp-launch.sh",
+        "mcp",
+        "--transport",
+        "stdio"
+      ]
+    }
+  },
+  "skills": {
+    "calling-llms": {
+      "name": "calling-llms",
+      "description": "Use when sending chat completions through liter-llm and routing to a specific provider via the `provider/model` prefix. Covers the chat call shape, provider routing, model_hint, message roles, and error categories."
+    },
+    "embeddings-and-search": {
+      "name": "embeddings-and-search",
+      "description": "Use when generating embeddings, calling the 12 web-search providers, or running OCR over documents with the 4 OCR providers through liter-llm. Covers embed, search, and ocr methods plus reranking."
+    },
+    "liter-llm": {
+      "name": "liter-llm",
+      "description": "Universal LLM API client for 174 providers with native bindings for 14 languages. Use when writing code that calls LLM APIs via liter-llm in Python, TypeScript, Rust, Go, Java, C#, Ruby, PHP, Elixir, WASM, or C, when running the OpenAI-compatible proxy, or when calling LLMs through the MCP server. Covers chat, streaming, tool calling, embeddings, image generation, speech, transcription, moderation, web search, OCR, reranking, provider routing, middleware, and configuration."
+    },
+    "running-the-proxy": {
+      "name": "running-the-proxy",
+      "description": "Use when running the `liter-llm api` OpenAI-compatible gateway — virtual keys, per-key rate limits, budgets, cost tracking, and model routing. Covers the TOML config and the 22 REST endpoints."
+    },
+    "streaming-responses": {
+      "name": "streaming-responses",
+      "description": "Use when streaming tokens incrementally from an LLM via liter-llm over SSE or async iterators. Covers chat_stream, delta handling, and null-content chunks."
+    },
+    "tool-calling": {
+      "name": "tool-calling",
+      "description": "Use when defining functions/tools for an LLM to call through liter-llm, or requesting structured JSON outputs. Covers tool schemas, tool_calls handling, and response formats."
+    },
+    "using-the-mcp-server": {
+      "name": "using-the-mcp-server",
+      "description": "Use when calling LLM APIs through the liter-llm MCP server's 22 tools, and to decide when MCP beats the CLI or SDK. Covers the tool surface, the auto-installing launcher, and authentication."
+    }
+  }
+}

package/.opencode/ai-rulez-content.js

@@ -0,0 +1,167 @@
+// AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+// Content-Hash: blake3:822c510deb007e4f72877ad42f29918d0499f210ae363e82d465a0f0331ab294
+// Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
+// Schema-Version: v1
+
+// Generated by ai-rulez. Registers the skills, commands, agents, and MCP servers bundled with
+// this plugin in OpenCode v2. OpenCode only scans its own config directories, so a plugin installed from
+// npm has to register its bundled content itself.
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const root = import.meta.dirname;
+
+// Returns the text after a leading YAML frontmatter block. The frontmatter fields the
+// helper needs (name, description) are resolved when the bundle is generated and read
+// from ai-rulez-bundle.json, so no YAML is parsed here.
+function body(text) {
+  const match = /^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/u.exec(text);
+  return match ? match[1] : text;
+}
+
+function skip(kind, name, error) {
+  console.warn(`ai-rulez: skipping bundled ${kind} ${name}: ${error?.message ?? error}`);
+}
+
+async function entries(dir) {
+  try {
+    return (await readdir(path.join(root, dir), { withFileTypes: true })).toSorted((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+  } catch {
+    return [];
+  }
+}
+
+async function readBundle() {
+  try {
+    return JSON.parse(await readFile(path.join(root, "ai-rulez-bundle.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// Plugin install directory: the parent of the .opencode directory this file lives in.
+const pluginRoot = path.dirname(root);
+
+// Resolves ${PLUGIN_ROOT} to the install directory and ${NAME} to process.env at runtime,
+// so no install path or secret is baked into the package.
+function expand(value) {
+  return value.replaceAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/gu, (_, name) =>
+    name === "PLUGIN_ROOT" ? pluginRoot : (process.env[name] ?? ""),
+  );
+}
+
+function mcpServer(server) {
+  if (server.type === "remote") {
+    const entry = { type: "remote", url: expand(server.url) };
+    if (server.disabled) entry.disabled = true;
+    return entry;
+  }
+  const entry = { type: "local", command: server.command.map(expand) };
+  if (server.disabled) entry.disabled = true;
+  if (server.environment) {
+    entry.environment = Object.fromEntries(
+      Object.entries(server.environment).map(([key, value]) => [key, expand(value)]),
+    );
+  }
+  return entry;
+}
+
+async function load() {
+  const bundle = await readBundle();
+  const skills = [];
+  for (const entry of await entries("skills")) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(root, "skills", entry.name, "SKILL.md");
+    try {
+      const info = bundle.skills?.[entry.name] ?? {};
+      skills.push({
+        id: entry.name,
+        name: info.name || entry.name,
+        description: info.description,
+        path: file,
+        content: body(await readFile(file, "utf8")),
+      });
+    } catch (error) {
+      skip("skill", entry.name, error);
+    }
+  }
+  const commands = [];
+  for (const entry of await entries("commands")) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const name = entry.name.slice(0, -3);
+    try {
+      const template = body(await readFile(path.join(root, "commands", entry.name), "utf8"));
+      commands.push({ name, description: bundle.commands?.[name]?.description, template });
+    } catch (error) {
+      skip("command", name, error);
+    }
+  }
+  const agents = [];
+  for (const entry of await entries("agents")) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const id = entry.name.slice(0, -3);
+    try {
+      // The bundle holds settings resolved at generation time (the model in particular).
+      const system = body(await readFile(path.join(root, "agents", entry.name), "utf8"));
+      agents.push({ id, system: system.trim(), settings: bundle.agents?.[id] ?? {} });
+    } catch (error) {
+      skip("agent", id, error);
+    }
+  }
+  return { skills, commands, agents, mcp: bundle.mcp ?? {} };
+}
+
+export async function registerBundledContent(ctx) {
+  const { skills, commands, agents, mcp } = await load();
+  if (skills.length > 0) {
+    await ctx.skill.transform((editor) => {
+      for (const skill of skills) if (!editor.get(skill.id)) editor.add(skill);
+    });
+  }
+  if (commands.length > 0) {
+    await ctx.command.transform((editor) => {
+      for (const command of commands) {
+        editor.add({
+          name: command.name,
+          description: command.description,
+          execute: async ({ sessionID, prompt, delivery }) => {
+            await ctx.session.prompt({
+              ...prompt,
+              sessionID,
+              text: command.template.replaceAll("$ARGUMENTS", () => String(prompt.text ?? "")),
+              delivery,
+            });
+          },
+        });
+      }
+    });
+  }
+  if (agents.length > 0) {
+    await ctx.agent.transform((editor) => {
+      for (const agent of agents) {
+        editor.update(agent.id, (item) => {
+          const settings = agent.settings;
+          if (settings.description) item.description = settings.description;
+          if (["subagent", "primary", "all"].includes(settings.mode)) item.mode = settings.mode;
+          if (typeof settings.hidden === "boolean") item.hidden = settings.hidden;
+          if (typeof settings.model === "string" && settings.model.includes("/")) {
+            const split = settings.model.indexOf("/");
+            item.model = { providerID: settings.model.slice(0, split), id: settings.model.slice(split + 1) };
+            if (settings.variant) item.model.variant = settings.variant;
+          }
+          for (const key of ["temperature", "top_p"]) {
+            if (typeof settings[key] === "number") item.request.body[key] = settings[key];
+          }
+          if (agent.system) item.system = agent.system;
+        });
+      }
+    });
+  }
+  if (Object.keys(mcp).length > 0) {
+    await ctx.mcp.transform((editor) => {
+      for (const [name, server] of Object.entries(mcp)) editor.set(name, mcpServer(server));
+    });
+  }
+}

package/.opencode/plugins/liter-llm.js

@@ -1,6 +1,6 @@
 // AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 // Content-Hash: blake3:1ad3d813d05d2ed27d81f6e6848ad8cf124882181d5f4d5ca2e62e81d7bbc91c
-// Source-Hash: blake3:651c31e789b5b3a98bbebecbda0ea4f0b6222b63c8264db7c677af355c5fe27b
+// Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
 // Schema-Version: v1
 
 /**

package/.opencode/skills/calling-llms/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: calling-llms
+description: Use when sending chat completions through liter-llm and routing to a specific provider via the `provider/model` prefix. Covers the chat call shape, provider routing, model_hint, message roles, and error categories.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:116e9240923b4f529f06471698b0e15ce1a14688a5beb1cae28e0b62e3a2837f
+Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
+Schema-Version: v1
+-->
+
+# Calling LLMs
+
+Build a `ChatCompletionRequest` and send it with `client.chat(request)`. Create
+the client with `create_client(...)`. The model string is `provider/model`; the
+prefix selects the backend.
+
+```python
+import asyncio, json, os
+from liter_llm import create_client
+from liter_llm._internal_bindings import ChatCompletionRequest
+
+async def main() -> None:
+    client = create_client(api_key=os.environ["OPENAI_API_KEY"])
+    request = ChatCompletionRequest.from_json(json.dumps({
+        "model": "openai/gpt-4o",
+        "messages": [
+            {"role": "system", "content": "You are concise."},
+            {"role": "user", "content": "Name three Rust crates for HTTP."},
+        ],
+    }))
+    response = await client.chat(request)
+    print(response.choices[0].message.content)
+
+asyncio.run(main())
+```
+
+## Provider routing
+
+The model string's prefix selects the provider; build a request per backend:
+
+```python
+ChatCompletionRequest.from_json('{"model":"anthropic/claude-sonnet-4-20250514","messages":[...]}')
+ChatCompletionRequest.from_json('{"model":"google/gemini-2.0-flash","messages":[...]}')
+ChatCompletionRequest.from_json('{"model":"groq/llama3-70b","messages":[...]}')
+ChatCompletionRequest.from_json('{"model":"mistral/mistral-large-latest","messages":[...]}')
+ChatCompletionRequest.from_json('{"model":"bedrock/anthropic.claude-v2","messages":[...]}')
+```
+
+Set `model_hint` at construction to drop the prefix on every call:
+
+```python
+client = create_client(api_key="sk-...", model_hint="openai")
+# the request model can now omit the provider prefix:
+request = ChatCompletionRequest.from_json('{"model":"gpt-4o","messages":[...]}')
+await client.chat(request)  # routes to OpenAI
+```
+
+## Notes
+
+- Keys come from env vars (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …); never
+  hardcode them.
+- Without a prefix and without `model_hint`, routing fails.
+- Python errors are typed exceptions exported from `liter_llm`:
+  `AuthenticationError`, `RateLimitedError`, `BadRequestError`,
+  `ContextWindowExceededError`, `ContentPolicyError`, `NotFoundError`,
+  `ServerError`, `ServiceUnavailableError`, `LiterLlmTimeoutError`,
+  `BudgetExceededError` — all subclasses of `LiterLlmError`.

package/.opencode/skills/embeddings-and-search/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: embeddings-and-search
+description: Use when generating embeddings, calling the 12 web-search providers, or running OCR over documents with the 4 OCR providers through liter-llm. Covers embed, search, and ocr methods plus reranking.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:2486d6f9ae493f698ce3c5349658dacd142fb7dd3cd27a707c4acf3aa8877a55
+Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
+Schema-Version: v1
+-->
+
+# Embeddings and Search
+
+liter-llm exposes embeddings, web search (12 providers), OCR (4 providers), and
+reranking through the same `provider/model` routing convention.
+
+## Embeddings
+
+```python
+import asyncio, os
+from liter_llm import create_client
+from liter_llm._internal_bindings import EmbeddingRequest
+
+async def main() -> None:
+    client = create_client(api_key=os.environ["OPENAI_API_KEY"])
+    request = EmbeddingRequest.from_json(
+        '{"model":"openai/text-embedding-3-small","input":["first document","second document"]}'
+    )
+    response = await client.embed(request)
+    for item in response.data:
+        print(len(item.embedding))
+
+asyncio.run(main())
+```
+
+Many embedding models support dimension selection and base64 output; set
+`dimensions` / `encoding_format` in the request where the provider allows it.
+
+## Web search (12 providers)
+
+```python
+from liter_llm._internal_bindings import SearchRequest
+
+client = create_client(api_key=os.environ["BRAVE_API_KEY"])
+request = SearchRequest.from_json(
+    '{"model":"brave/web-search","query":"What is the Rust programming language?","max_results":5}'
+)
+response = await client.search(request)
+for result in response.results:
+    print(result.title, result.url)
+```
+
+## OCR (4 providers)
+
+```python
+from liter_llm._internal_bindings import OcrRequest
+
+client = create_client(api_key=os.environ["MISTRAL_API_KEY"])
+request = OcrRequest.from_json(
+    '{"model":"mistral/mistral-ocr-latest",'
+    '"document":{"type":"document_url","url":"https://example.com/invoice.pdf"}}'
+)
+response = await client.ocr(request)
+for page in response.pages:
+    print(page.index, page.markdown[:100])
+```
+
+## Reranking
+
+Build a `RerankRequest` (model, query, documents) and call `client.rerank(request)`
+to score and order candidate documents against a query for retrieval pipelines —
+combine it with `embed` for hybrid retrieval. Each result carries `index` and
+`relevance_score`. Routing follows the same `provider/model` convention.
+
+## Notes
+
+- Search and OCR providers each need their own API key (e.g. `BRAVE_API_KEY`,
+  `MISTRAL_API_KEY`); read them from env vars.
+- See the upstream provider reference for the full list of the 12 search and 4
+  OCR backends and their model identifiers.

package/.opencode/skills/liter-llm/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: liter-llm
+description: >-
+  Universal LLM API client for 174 providers with native bindings for 14
+  languages. Use when writing code that calls LLM APIs via liter-llm in Python,
+  TypeScript, Rust, Go, Java, C#, Ruby, PHP, Elixir, WASM, or C, when running
+  the OpenAI-compatible proxy, or when calling LLMs through the MCP server.
+  Covers chat, streaming, tool calling, embeddings, image generation, speech,
+  transcription, moderation, web search, OCR, reranking, provider routing,
+  middleware, and configuration.
+license: MIT
+metadata:
+  author: xberg-io
+  version: "0.1.0"
+  repository: https://github.com/xberg-io/liter-llm
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:4c225507a3afd50b57d77a64697e865deeb31b88a491ab3e8541cea22a5884ff
+Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
+Schema-Version: v1
+-->
+
+# Liter-LLM Universal LLM Client
+
+Liter-LLM is a universal LLM API client with a Rust core and native bindings for
+Python, TypeScript/Node.js, Go, Java, C#, Ruby, PHP, Elixir, WebAssembly, and C
+(FFI). One unified interface reaches 174 providers (OpenAI, Anthropic, Google
+Gemini, Groq, Mistral, Cohere, AWS Bedrock, Azure, and many more).
+
+## Capability map
+
+- **Modalities** — chat completions, streaming, tool/function calling,
+  structured outputs, embeddings, image generation, audio (speech,
+  transcription), moderation, web search, OCR, reranking, batch,
+  and file operations.
+- **Provider routing** — `provider/model` prefix selects the backend
+  (`openai/gpt-4o`, `anthropic/claude-sonnet-4-20250514`,
+  `gemini/gemini-2.0-flash`). Set `model_hint` to skip the prefix.
+- **Middleware** — response caching, rate limiting (RPM/TPM), cost tracking,
+  budget enforcement (`hard` / `soft`), fallback chains, circuit-breaker
+  cooldown, and background health checks.
+- **Search providers (12)** and **OCR providers (4)** — first-class `search`
+  and `ocr` methods routed by the same prefix convention.
+- **Proxy server** — `liter-llm api` exposes an OpenAI-compatible gateway with
+  22 REST endpoints, virtual API keys, budgets, and SSE streaming.
+- **MCP server** — `liter-llm mcp` exposes 22 tools mirroring the proxy
+  endpoints, for MCP-compatible clients (Claude Code, Claude Desktop).
+- **14 language bindings** — same surface, language-native naming (snake_case
+  for Python/Rust/Ruby/Go/Elixir/PHP, camelCase for TS/Node/WASM/C#/Java).
+
+## When to use the MCP server vs the SDK vs the proxy
+
+| Use the … | When you want to … | Entry point |
+|-----------|--------------------|-------------|
+| **MCP server** | Let the agent call LLM APIs directly as tools, with no glue code | `liter-llm mcp --transport stdio` (this plugin auto-registers it) |
+| **SDK / binding** | Write application code that calls LLMs in a specific language | `pip install liter-llm`, `cargo add liter-llm`, etc. |
+| **Proxy** | Give many apps/teams a shared OpenAI-compatible endpoint with keys, budgets, and rate limits | `liter-llm api --config liter-llm-proxy.toml` |
+
+Rule of thumb: reach for the MCP server inside an agent session; the SDK when
+building software; the proxy when centralizing access for multiple consumers.
+
+## Installation
+
+### CLI (proxy + MCP server)
+
+```bash
+# Homebrew (macOS / Linux)
+brew install xberg-io/tap/liter-llm
+
+# or run it without a persistent install (the CLI proxy package self-installs the binary)
+npx @xberg-io/liter-llm-cli --help
+uvx --from liter-llm-cli liter-llm --help
+
+# or download a prebuilt binary from the latest GitHub release:
+#   https://github.com/xberg-io/liter-llm/releases/latest
+
+# or build from source
+cargo install liter-llm-cli
+
+# or Docker (35MB image)
+docker pull ghcr.io/xberg-io/liter-llm
+```
+
+### Language bindings
+
+| Language | Install |
+|----------|---------|
+| Python | `pip install liter-llm` |
+| Node.js | `pnpm add @xberg-io/liter-llm` |
+| Rust | `cargo add liter-llm` |
+| Go | `go get github.com/xberg-io/liter-llm/packages/go/v2` |
+| Ruby | `gem install liter_llm` |
+| PHP | `composer require xberg-io/liter-llm` |
+| C# | `dotnet add package XbergIo.LiterLlm` |
+| WASM | `pnpm add @xberg-io/liter-llm-wasm` |
+
+## Quick start (Python, async)
+
+```python
+import asyncio
+import os
+from liter_llm import create_client
+from liter_llm._internal_bindings import ChatCompletionRequest
+
+async def main() -> None:
+    client = create_client(api_key=os.environ["OPENAI_API_KEY"])
+    request = ChatCompletionRequest.from_json(
+        '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hello!"}]}'
+    )
+    response = await client.chat(request)
+    print(response.choices[0].message.content)
+
+asyncio.run(main())
+```
+
+## Provider routing
+
+The prefix before `/` in the request's `model` selects the provider:
+
+```python
+ChatCompletionRequest.from_json('{"model":"openai/gpt-4o","messages":[...]}')
+ChatCompletionRequest.from_json('{"model":"anthropic/claude-sonnet-4-20250514","messages":[...]}')
+ChatCompletionRequest.from_json('{"model":"gemini/gemini-2.0-flash","messages":[...]}')
+ChatCompletionRequest.from_json('{"model":"groq/llama3-70b","messages":[...]}')
+```
+
+API keys come from environment variables: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+`GEMINI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `CO_API_KEY`, and AWS
+credentials for Bedrock.
+
+## Configuration
+
+Pass basic options to `create_client(...)` (`api_key`, `base_url`,
+`timeout_secs`, `max_retries`, `model_hint`), or set the full surface in a
+`liter-llm.toml` (SDK) / `liter-llm-proxy.toml` (proxy) — both auto-discover
+from the cwd upward.
+
+```toml
+# liter-llm.toml
+api_key = "${OPENAI_API_KEY}"
+model_hint = "openai"
+timeout_secs = 120
+max_retries = 5
+
+[cache]
+max_entries = 512
+ttl_seconds = 600
+
+[budget]
+global_limit = 50.0
+enforcement = "hard"
+
+[rate_limit]
+rpm = 60
+tpm = 100000
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `api_key` | required | Provider key, wrapped in `SecretString` (never logged). |
+| `base_url` | from registry | Override the provider base URL. |
+| `model_hint` | none | Pre-resolve a provider, skipping the prefix lookup. |
+| `timeout_secs` | 60 | Request timeout in seconds. |
+| `max_retries` | 3 | Retries on 429/5xx with exponential backoff. |
+| `cache` | none | `max_entries`, `ttl_seconds`. |
+| `budget` | none | `global_limit`, `model_limits`, `enforcement`. |
+| `rate_limit` | none | `rpm`, `tpm`. |
+| `cost_tracking` | false | Per-request cost tracking. |
+| `tracing` | false | OpenTelemetry spans. |
+
+## Proxy server
+
+```bash
+liter-llm api --config liter-llm-proxy.toml
+```
+
+22 OpenAI-compatible endpoints, model routing by prefix, virtual API keys,
+per-key RPM/TPM limits, cost tracking, budget enforcement, response caching, SSE
+streaming, and an OpenAPI 3.1 spec at `/openapi.json`.
+
+## MCP server
+
+```bash
+liter-llm mcp --transport stdio   # for Claude Code / Claude Desktop
+liter-llm mcp --transport http --port 3001
+```
+
+This plugin auto-registers the stdio server via `scripts/mcp-launch.sh`. The 22
+tools mirror the proxy endpoints: `chat`, `embed`, `generate_image`, `speech`,
+`transcribe`, `moderate`, `rerank`, `search`, `ocr`, `list_models`; file ops
+(`create_file`, `list_files`, `retrieve_file`, `delete_file`, `file_content`);
+batch ops (`create_batch`, `list_batches`, `retrieve_batch`, `cancel_batch`);
+and Responses API (`create_response`, `retrieve_response`, `cancel_response`).
+
+## Common pitfalls
+
+1. **Provider prefix is required** — use `"provider/model"` unless `model_hint`
+   is set, or routing fails.
+2. **API keys are SecretString** — never logged or serialized. Read from env
+   vars; never hardcode.
+3. **Python methods are async** — `await` inside an async context.
+4. **Naming conventions differ** — camelCase for TS/Node/WASM/C#/Java,
+   snake_case elsewhere.
+5. **Streaming chunks may have null content** — null-check
+   `chunk.choices[0].delta.content` before use.
+6. **Budget modes** — `hard` rejects over-budget requests; `soft` logs and
+   allows.
+
+## Additional resources
+
+- Upstream docs: <https://docs.liter-llm.xberg.io>
+- GitHub: <https://github.com/xberg-io/liter-llm>

package/.opencode/skills/running-the-proxy/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: running-the-proxy
+description: Use when running the `liter-llm api` OpenAI-compatible gateway — virtual keys, per-key rate limits, budgets, cost tracking, and model routing. Covers the TOML config and the 22 REST endpoints.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:f64a695a6f03738acb7f80e2d91d2446346006e3a2c4858b5fe87f88f14c86f5
+Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
+Schema-Version: v1
+-->
+
+# Running the Proxy
+
+`liter-llm api` is a drop-in OpenAI-compatible gateway: 22 REST endpoints that
+route to 174 providers, with multi-tenant virtual keys, rate limits, budgets,
+and cost tracking.
+
+## Start it
+
+```bash
+liter-llm api --config liter-llm-proxy.toml
+```
+
+The proxy auto-discovers `liter-llm-proxy.toml` in the current directory.
+
+## Configuration
+
+```toml
+[server]
+host = "0.0.0.0"
+port = 4000
+
+[general]
+master_key = "${LITER_LLM_MASTER_KEY}"
+
+# Each [[models]] entry maps a routable name to a provider/model and its key.
+[[models]]
+name = "gpt-4o"
+provider_model = "openai/gpt-4o"
+api_key = "${OPENAI_API_KEY}"
+
+[[models]]
+name = "claude-sonnet"
+provider_model = "anthropic/claude-sonnet-4-20250514"
+api_key = "${ANTHROPIC_API_KEY}"
+
+# Virtual keys scope which configured model names a caller may use.
+[[keys]]
+key = "sk-team-frontend"
+models = ["gpt-4o", "claude-sonnet"]
+rpm = 60
+tpm = 100000
+budget_limit = 50.0
+```
+
+`${ENV_VAR}` interpolation keeps secrets out of the file.
+
+## Call it like OpenAI
+
+```bash
+curl http://localhost:4000/v1/chat/completions \
+  -H "Authorization: Bearer sk-team-frontend" \
+  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
+```
+
+## Notes
+
+- Virtual keys scope which models a caller may use and carry their own RPM/TPM
+  and budget limits; the `master_key` administers them.
+- The OpenAPI 3.1 spec is served at `/openapi.json`.
+- Endpoints cover chat, embeddings, images, audio, moderations, files, batches,
+  responses, and model listing.
+- Docker: `docker run -p 4000:4000 -e LITER_LLM_MASTER_KEY=sk-key ghcr.io/xberg-io/liter-llm`.

package/.opencode/skills/streaming-responses/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: streaming-responses
+description: Use when streaming tokens incrementally from an LLM via liter-llm over SSE or async iterators. Covers chat_stream, delta handling, and null-content chunks.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:13410510899be94ef40712ffcb27a284ef4ac4977b6e45b38b014d60e913f995
+Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
+Schema-Version: v1
+-->
+
+# Streaming Responses
+
+Use `chat_stream(...)` to receive tokens as they are produced instead of waiting
+for the full completion. The proxy streams over SSE; bindings expose async
+iterators.
+
+## Python
+
+```python
+import asyncio, os
+from liter_llm import create_client
+from liter_llm._internal_bindings import ChatCompletionRequest
+
+async def main() -> None:
+    client = create_client(api_key=os.environ["OPENAI_API_KEY"])
+    request = ChatCompletionRequest.from_json(
+        '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Tell me a story"}],"stream":true}'
+    )
+    async for chunk in client.chat_stream(request):
+        if chunk.choices and chunk.choices[0].delta.content:
+            print(chunk.choices[0].delta.content, end="", flush=True)
+    print()
+
+asyncio.run(main())
+```
+
+## TypeScript
+
+```typescript
+import { createClient } from "@xberg-io/liter-llm";
+
+const client = createClient(process.env.OPENAI_API_KEY!);
+const chunks = await client.chatStream({
+  model: "openai/gpt-4o",
+  messages: [{ role: "user", content: "Tell me a story" }],
+});
+for await (const chunk of chunks) {
+  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
+}
+```
+
+## Notes
+
+- The first and last chunks often carry null content. Always null-check
+  `chunk.choices[0].delta.content` (Python) or
+  `chunk.choices[0]?.delta?.content` (TypeScript) before using it.
+- Tool-call deltas arrive in `delta.tool_calls` (Python) /
+  `delta.toolCalls` (TypeScript); accumulate `function.arguments` fragments
+  across chunks before parsing.
+- Through the proxy, request streaming with `"stream": true` on
+  `/v1/chat/completions`.

package/.opencode/skills/tool-calling/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: tool-calling
+description: Use when defining functions/tools for an LLM to call through liter-llm, or requesting structured JSON outputs. Covers tool schemas, tool_calls handling, and response formats.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:636c5d6448b2e3c003bd5caec347391513d72e415ceaef0740241141bc363b35
+Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
+Schema-Version: v1
+-->
+
+# Tool Calling
+
+Pass a `tools` array of function definitions; the model may respond with
+`tool_calls` instead of (or alongside) text. Execute the named function and feed
+the result back as a `tool` message.
+
+## Python
+
+```python
+import asyncio, json, os
+from liter_llm import create_client
+from liter_llm._internal_bindings import ChatCompletionRequest
+
+payload = {
+    "model": "openai/gpt-4o",
+    "messages": [{"role": "user", "content": "What is the weather in Berlin?"}],
+    "tools": [
+        {
+            "type": "function",
+            "function": {
+                "name": "get_weather",
+                "description": "Get the current weather for a location",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string", "description": "City name"},
+                    },
+                    "required": ["location"],
+                },
+            },
+        }
+    ],
+    "tool_choice": "auto",
+}
+
+async def main() -> None:
+    client = create_client(api_key=os.environ["OPENAI_API_KEY"])
+    request = ChatCompletionRequest.from_json(json.dumps(payload))
+    response = await client.chat(request)
+    for call in response.choices[0].message.tool_calls or []:
+        print(call.function.name, call.function.arguments)  # arguments is a JSON string
+
+asyncio.run(main())
+```
+
+## Structured outputs
+
+Request strict JSON with `response_format`:
+
+```python
+request = ChatCompletionRequest.from_json(json.dumps({
+    "model": "openai/gpt-4o",
+    "messages": [{"role": "user", "content": "Extract name and age as JSON."}],
+    "response_format": {"type": "json_object"},
+}))
+response = await client.chat(request)
+```
+
+## Notes
+
+- `function.arguments` is a JSON **string** — parse it before use.
+- Append each tool result as a message with `role="tool"` and the matching
+  `tool_call_id`, then call `chat` again to let the model continue.
+- Tool support and JSON-mode availability vary by provider; check the provider
+  reference if a model ignores `tools`.

package/.opencode/skills/using-the-mcp-server/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: using-the-mcp-server
+description: Use when calling LLM APIs through the liter-llm MCP server's 22 tools, and to decide when MCP beats the CLI or SDK. Covers the tool surface, the auto-installing launcher, and authentication.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:bb42aaf38dca362b154240ddbee4e03bb76614ff452facc744f7d560cfc6d523
+Source-Hash: blake3:8e912c45817ab091b08e38cc7bf8e0a4d28b63546499306a907ade79e33dbe17
+Schema-Version: v1
+-->
+
+# Using the MCP Server
+
+The `liter-llm` MCP server exposes 22 tools that mirror the proxy's REST
+endpoints, so an MCP-compatible client (Claude Code, Claude Desktop) can call
+174 LLM providers as tools with no glue code.
+
+## How it runs in this plugin
+
+The plugin auto-registers the server. Its command is the bundled launcher
+`scripts/mcp-launch.sh`, which execs `liter-llm mcp --transport stdio`. On first
+run the launcher resolves a `liter-llm` binary: it reuses one on `PATH`, then
+tries `npx`/`uvx`, then Homebrew, then downloads a checksum-verified prebuilt
+from the tool's latest GitHub release. Override with
+`LITER_LLM_LAUNCHER=auto|npx|uvx|brew|download`.
+
+To run it manually:
+
+```bash
+liter-llm mcp --transport stdio          # for Claude Code / Claude Desktop
+liter-llm mcp --transport http --port 3001
+```
+
+## The 22 tools
+
+Modality tools: `chat`, `embed`, `generate_image`, `speech`, `transcribe`,
+`moderate`, `rerank`, `search`, `ocr`.
+
+Model listing: `list_models`.
+
+File operations: `create_file`, `list_files`, `retrieve_file`, `delete_file`,
+`file_content`.
+
+Batch operations: `create_batch`, `list_batches`, `retrieve_batch`,
+`cancel_batch`.
+
+Responses API: `create_response`, `retrieve_response`, `cancel_response`.
+
+## Authentication
+
+stdio has no per-request auth headers, so the server binds auth once at startup
+via `[mcp]` config: set `mcp.stdio_key_id` to bind a specific virtual key, or
+`mcp.stdio_trust_local = true` for fully trusted local environments. Provider
+keys still come from env vars.
+
+## When to prefer MCP over the CLI or SDK
+
+- **Prefer MCP** inside an agent session: the agent invokes tools directly, with
+  no code to write or process to manage.
+- **Prefer the SDK** when building application software in a specific language.
+- **Prefer the proxy** when many apps or teams need a shared OpenAI-compatible
+  endpoint with keys, budgets, and rate limits.

package/README.md

@@ -1,6 +1,6 @@
 # liter-llm
 
-Universal LLM API client for 165 providers — chat, streaming, tools, embeddings, search, OCR, plus an OpenAI-compatible proxy and an MCP server, in your agent.
+Universal LLM API client for 174 providers — chat, streaming, tools, embeddings, search, OCR, plus an OpenAI-compatible proxy and an MCP server, in your agent.
 
 <!-- ~keep TODO: add screenshot -->
 
@@ -47,7 +47,7 @@ Set provider API keys via environment variables (`OPENAI_API_KEY`,
 
 | Skill | Trigger |
 |-------|---------|
-| **liter-llm** | Universal LLM client surface — chat, streaming, tools, embeddings, image/audio, moderation, search, OCR, reranking — across 165 providers and 14 language bindings. Use when writing LLM code in any supported language or choosing between the SDK, proxy, and MCP server. |
+| **liter-llm** | Universal LLM client surface — chat, streaming, tools, embeddings, image/audio, moderation, search, OCR, reranking — across 174 providers and 14 language bindings. Use when writing LLM code in any supported language or choosing between the SDK, proxy, and MCP server. |
 | **calling-llms** | Use when sending chat completions and routing to a specific provider via the `provider/model` prefix. |
 | **streaming-responses** | Use when streaming tokens incrementally over SSE or async iterators. |
 | **tool-calling** | Use when defining functions/tools for the model to call, or requesting structured outputs. |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xberg-io/opencode-liter-llm",
-  "version": "2.1.2",
-  "description": "Universal LLM API client for 165 providers — chat, streaming, tools, embeddings, search, OCR, plus an OpenAI-compatible proxy and an MCP server.",
+  "version": "2.2.0",
+  "description": "Universal LLM API client for 174 providers — chat, streaming, tools, embeddings, search, OCR, plus an OpenAI-compatible proxy and an MCP server.",
   "keywords": [
     "llm",
     "openai",
@@ -23,9 +23,10 @@
   "files": [
     ".opencode/",
     "assets/",
-    "README.md"
+    "README.md",
+    "scripts/"
   ],
   "dependencies": {
-    "@opencode-ai/plugin": "^1.17.8"
+    "@opencode/plugin": "^2.0.20"
   }
 }

package/scripts/mcp-launch.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO="xberg-io/liter-llm"
+NPM_PKG="@xberg-io/liter-llm-cli"
+PYPI_PKG="liter-llm-cli"
+
+log() { printf 'liter-llm-launch: %s\n' "$*" >&2; }
+die() {
+  log "error: $*"
+  exit 1
+}
+
+LAUNCHER="${LITER_LLM_LAUNCHER:-auto}"
+case "$LAUNCHER" in
+auto | npx | uvx | brew | download) ;;
+*) die "invalid LITER_LLM_LAUNCHER='$LAUNCHER' (expected auto|npx|uvx|brew|download)" ;;
+esac
+
+want() { [ "$LAUNCHER" = "auto" ] || [ "$LAUNCHER" = "$1" ]; }
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [ -z "$PLUGIN_ROOT" ]; then
+  PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+fi
+
+BINARY_NAME="liter-llm"
+case "$(uname -s)" in
+MINGW* | MSYS* | CYGWIN* | Windows_NT) BINARY_NAME="liter-llm.exe" ;;
+esac
+BIN_DIR="$PLUGIN_ROOT/bin"
+BIN="$BIN_DIR/$BINARY_NAME"
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+runs_ok() { [ -x "$1" ] && "$1" --version >/dev/null 2>&1; }
+
+if runs_ok "$BIN"; then
+  log "using cached liter-llm at $BIN"
+  exec "$BIN" "$@"
+fi
+if have "$BINARY_NAME"; then
+  PATH_BIN="$(command -v "$BINARY_NAME")"
+  if runs_ok "$PATH_BIN"; then
+    log "using liter-llm on PATH ($PATH_BIN)"
+    exec "$PATH_BIN" "$@"
+  fi
+fi
+
+if want npx && have npx; then
+  log "probing npx $NPM_PKG@latest ..."
+  scratch="$(mktemp -d)"
+  if (cd "$scratch" && npx -y "$NPM_PKG@latest" --version >/dev/null 2>&1); then
+    log "launching via npx $NPM_PKG@latest"
+    cd "$scratch"
+    exec npx -y "$NPM_PKG@latest" "$@"
+  fi
+  rm -rf "$scratch"
+  log "npx $NPM_PKG not available (no CLI bin yet); falling through"
+fi
+
+if want uvx && have uvx; then
+  log "probing uvx --from $PYPI_PKG $BINARY_NAME ..."
+  if uvx --from "$PYPI_PKG" "$BINARY_NAME" --version >/dev/null 2>&1; then
+    log "launching via uvx --from $PYPI_PKG $BINARY_NAME"
+    exec uvx --from "$PYPI_PKG" "$BINARY_NAME" "$@"
+  fi
+  log "uvx $PYPI_PKG not available (no CLI entry point yet); falling through"
+fi
+
+if want brew && have brew; then
+  log "installing via 'brew install xberg-io/tap/liter-llm' ..."
+  if brew install xberg-io/tap/liter-llm >&2; then
+    if have "$BINARY_NAME"; then
+      BREW_BIN="$(command -v "$BINARY_NAME")"
+      runs_ok "$BREW_BIN" && exec "$BREW_BIN" "$@"
+    fi
+    log "brew install reported success but liter-llm is not on PATH; falling through"
+  else
+    log "brew install failed; falling through"
+  fi
+fi
+
+if have curl; then
+  fetch() { curl -fsSL --retry 3 -o "$2" "$1"; }
+  fetch_stdout() { curl -fsSL --retry 3 "$1"; }
+elif have wget; then
+  fetch() { wget -q -O "$2" "$1"; }
+  fetch_stdout() { wget -q -O - "$1"; }
+else
+  fetch() { return 1; }
+  fetch_stdout() { return 1; }
+fi
+
+if have sha256sum; then
+  sha256() { sha256sum "$1" | awk '{print $1}'; }
+elif have shasum; then
+  sha256() { shasum -a 256 "$1" | awk '{print $1}'; }
+else
+  sha256() { return 1; }
+fi
+
+try_download() {
+  if ! have curl && ! have wget; then
+    log "download: no curl or wget available; falling through"
+    return 1
+  fi
+
+  arch="$(uname -m)"
+  local target ext
+  case "$(uname -s)" in
+  Darwin)
+    case "$arch" in
+    arm64 | aarch64) target="aarch64-apple-darwin" ;;
+    *)
+      log "download: Intel macOS (x86_64) prebuilt is not shipped; falling through"
+      return 1
+      ;;
+    esac
+    ext="tar.gz"
+    ;;
+  Linux)
+    case "$arch" in
+    aarch64 | arm64) target="aarch64-unknown-linux-gnu" ;;
+    *) target="x86_64-unknown-linux-gnu" ;;
+    esac
+    ext="tar.gz"
+    ;;
+  MINGW* | MSYS* | CYGWIN* | Windows_NT)
+    target="x86_64-pc-windows-msvc"
+    ext="zip"
+    ;;
+  *)
+    log "download: unsupported platform $(uname -s) $arch; falling through"
+    return 1
+    ;;
+  esac
+
+  local api_json tag version
+  api_json="$(fetch_stdout "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null)" ||
+    {
+      log "download: could not query latest release; falling through"
+      return 1
+    }
+  tag="$(printf '%s' "$api_json" | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)"
+  [ -n "$tag" ] || {
+    log "download: could not parse tag_name from API; falling through"
+    return 1
+  }
+  version="${tag#v}"
+
+  local stem base_url asset asset_url sums_url
+  stem="liter-llm-${version}-${target}"
+  base_url="https://github.com/${REPO}/releases/download/${tag}"
+  asset="${stem}.${ext}"
+  asset_url="${base_url}/${asset}"
+  sums_url="${base_url}/SHA256SUMS-${version}.txt"
+
+  local tmp
+  tmp="$(mktemp -d)"
+  # shellcheck disable=SC2064
+  trap "rm -rf '$tmp'" RETURN
+
+  log "downloading $asset from $tag ..."
+  if ! fetch "$asset_url" "$tmp/$asset"; then
+    log "download: asset not found ($asset_url); falling through"
+    return 1
+  fi
+
+  if sha256 "$tmp/$asset" >/dev/null 2>&1 && fetch "$sums_url" "$tmp/checksums.txt" 2>/dev/null; then
+    local expected actual
+    expected="$(awk -v f="$asset" '{name=$NF; sub(/^[*]/, "", name); if (name == f) print $1}' "$tmp/checksums.txt")"
+    if [ -n "$expected" ]; then
+      actual="$(sha256 "$tmp/$asset")"
+      [ "$expected" = "$actual" ] || die "checksum mismatch for $asset (expected $expected, got $actual)"
+      log "checksum verified"
+    else
+      log "WARNING: no checksum entry for $asset in SHA256SUMS-${version}.txt; proceeding over HTTPS unverified"
+    fi
+  else
+    log "WARNING: could not verify checksum (no sha256 tool or no SHA256SUMS file); proceeding over HTTPS unverified"
+  fi
+
+  local ex src_bin
+  ex="$tmp/extracted"
+  mkdir -p "$ex"
+  case "$ext" in
+  tar.gz) tar -xzf "$tmp/$asset" -C "$ex" ;;
+  zip)
+    have unzip || {
+      log "download: need unzip to extract $asset; falling through"
+      return 1
+    }
+    unzip -qo "$tmp/$asset" -d "$ex"
+    ;;
+  esac
+  src_bin="$ex/$stem/$BINARY_NAME"
+  [ -f "$src_bin" ] || {
+    log "download: $BINARY_NAME not found inside $asset; falling through"
+    return 1
+  }
+
+  rm -rf "$BIN_DIR"
+  mkdir -p "$BIN_DIR"
+  mv "$src_bin" "$BIN"
+  chmod +x "$BIN"
+  log "installed liter-llm $version to $BIN"
+  runs_ok "$BIN" || {
+    log "download: installed binary failed to run; falling through"
+    return 1
+  }
+  return 0
+}
+
+if want download; then
+  if try_download; then
+    exec "$BIN" "$@"
+  fi
+fi
+
+die "could not locate or install liter-llm. Install it with one of:
+  brew install xberg-io/tap/liter-llm
+  cargo install liter-llm-cli
+or download a prebuilt archive from https://github.com/${REPO}/releases/latest
+then re-run, or set LITER_LLM_LAUNCHER to force a method (auto|npx|uvx|brew|download)."