diff --git a/External/routerbase-api-integration/SKILL.md b/External/routerbase-api-integration/SKILL.md new file mode 100644 index 0000000..e53a4e9 --- /dev/null +++ b/External/routerbase-api-integration/SKILL.md @@ -0,0 +1,93 @@ +--- +name: routerbase-api-integration +description: Integrate applications with RouterBase, the OpenAI-compatible model gateway at https://routerbase.com/v1. Use when migrating OpenAI SDK calls to RouterBase, configuring RouterBase API keys, implementing chat completions, streaming, tool calling, JSON mode, vision inputs, request validation, error handling, or documenting RouterBase setup for Python, JavaScript, curl, LangChain, LlamaIndex, Vercel AI SDK, Cursor, Continue, or other OpenAI-compatible clients. +metadata: + author: zenlee123 + category: External +--- + +# RouterBase API Integration + +## Overview + +Use [routerbase](https://routerbase.com) as an OpenAI-compatible gateway for GPT, Claude, Gemini, and other supported models. This skill helps agents migrate existing OpenAI-compatible code, keep API keys server-side, and produce concise, testable RouterBase integration snippets. + +Read `references/routerbase-api.md` when exact endpoint details, headers, or examples are needed. + +## Integration Workflow + +1. Identify whether the user is asking for migration, a new integration, debugging, or documentation. +2. Keep credentials out of client/browser code. Prefer `ROUTERBASE_API_KEY` in server-side environment configuration. +3. Reuse the user's existing OpenAI-compatible client when possible. Change the base URL to `https://routerbase.com/v1`, then swap the `model` to a RouterBase model ID. +4. Preserve standard OpenAI request shapes unless RouterBase docs or the selected model require a model-specific field. +5. For model IDs, use the live model catalog when an API key is available; otherwise use documented examples only as a starting point and tell the user to verify current availability. +6. Add a minimal smoke test, but do not run it unless credentials are present and the user expects a live API call. + +## Common Patterns + +### Python + +```python +import os +from openai import OpenAI + +client = OpenAI( + api_key=os.environ["ROUTERBASE_API_KEY"], + base_url="https://routerbase.com/v1", +) + +response = client.chat.completions.create( + model="google/gemini-2.5-flash", + messages=[{"role": "user", "content": "Write one sentence about model routing."}], +) + +print(response.choices[0].message.content) +``` + +### JavaScript + +```js +import OpenAI from "openai"; + +const client = new OpenAI({ + apiKey: process.env.ROUTERBASE_API_KEY, + baseURL: "https://routerbase.com/v1", +}); + +const response = await client.chat.completions.create({ + model: "google/gemini-2.5-flash", + messages: [{ role: "user", content: "Write one sentence about model routing." }], +}); + +console.log(response.choices[0].message.content); +``` + +### curl + +```bash +curl -X POST https://routerbase.com/v1/chat/completions \ + -H "Authorization: Bearer $ROUTERBASE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "google/gemini-2.5-flash", + "messages": [{"role": "user", "content": "What is 2+2?"}] + }' +``` + +## Implementation Guardrails + +- Never paste or log real API keys. Use placeholders like `sk-rb-...` only in docs. +- Never put RouterBase keys in browser, mobile, or public repository code. +- Keep examples OpenAI-compatible unless the user asks for a framework-specific adapter. +- For streaming, set `stream: true` and process Server-Sent Events or SDK stream chunks. +- For tool calling and JSON mode, keep the standard OpenAI fields `tools` and `response_format`. +- For multimodal chat, use OpenAI content parts with `text` and `image_url`. +- If a live request fails, check headers, model ID, endpoint path, rate limits, and account access before changing application logic. + +## Output Checklist + +- Include the changed base URL. +- Include where `ROUTERBASE_API_KEY` should be configured. +- Include one minimal request example. +- Include a clear note when model IDs or prices should be checked against the live RouterBase catalog. +- Include a test command or dry-run validation path. diff --git a/External/routerbase-api-integration/references/routerbase-api.md b/External/routerbase-api-integration/references/routerbase-api.md new file mode 100644 index 0000000..33a3484 --- /dev/null +++ b/External/routerbase-api-integration/references/routerbase-api.md @@ -0,0 +1,130 @@ +# RouterBase API Reference Notes + +Use this reference for exact integration details. Prefer the live RouterBase documentation when making production claims. + +## Product Facts + +- RouterBase routes LLMs through one OpenAI-compatible API. +- The public docs describe the base URL as `https://routerbase.com/v1`. +- RouterBase positions itself as a drop-in replacement for the OpenAI SDK: change the client base URL and use a RouterBase API key. +- Publicly documented benefits include 200+ models, one API key, smart routing, automatic fallback, unified billing, and usage analytics. + +Source pages: + +- https://routerbase.com +- https://docs.routerbase.com +- https://docs.routerbase.com/api-reference/chat-completions + +## Authentication + +Every API request needs: + +```http +Authorization: Bearer +Content-Type: application/json +``` + +Use `ROUTERBASE_API_KEY` in examples. Never place keys in frontend code. + +## Core Endpoints + +```text +POST https://routerbase.com/v1/chat/completions +POST https://routerbase.com/v1/images/generations +POST https://routerbase.com/v1/videos/generations +POST https://routerbase.com/v1/audio/speech +POST https://routerbase.com/v1/audio/generations +GET https://routerbase.com/api/v1/models +GET https://routerbase.com/api/v1/models/{model_id} +GET https://routerbase.com/api/v1/models/{model_id}/pricing +GET https://routerbase.com/api/v1/pricing +``` + +## Chat Completion Fields + +Common OpenAI-compatible fields: + +- `model` +- `messages` +- `temperature` +- `max_tokens` +- `top_p` +- `stream` +- `stop` +- `seed` +- `response_format` +- `presence_penalty` +- `frequency_penalty` +- `tools` +- `prompt_cache_key` + +## Examples + +Python: + +```python +import os +from openai import OpenAI + +client = OpenAI( + api_key=os.environ["ROUTERBASE_API_KEY"], + base_url="https://routerbase.com/v1", +) + +response = client.chat.completions.create( + model="google/gemini-2.5-flash", + messages=[{"role": "user", "content": "What is 2+2?"}], +) +``` + +JavaScript: + +```js +import OpenAI from "openai"; + +const client = new OpenAI({ + apiKey: process.env.ROUTERBASE_API_KEY, + baseURL: "https://routerbase.com/v1", +}); +``` + +Streaming: + +```python +stream = client.chat.completions.create( + model="google/gemini-2.5-flash", + messages=[{"role": "user", "content": "Write a haiku"}], + stream=True, +) + +for chunk in stream: + print(chunk.choices[0].delta.content or "", end="") +``` + +Vision content parts: + +```json +{ + "model": "google/gemini-2.5-flash", + "messages": [ + { + "role": "user", + "content": [ + { "type": "text", "text": "What's in this image?" }, + { "type": "image_url", "image_url": { "url": "https://example.com/image.png" } } + ] + } + ] +} +``` + +## Validation + +When debugging: + +1. Confirm `ROUTERBASE_API_KEY` is set server-side. +2. Confirm `base_url` or `baseURL` is exactly `https://routerbase.com/v1`. +3. Confirm headers include bearer auth and JSON content type. +4. Confirm model ID exists in the live catalog. +5. Confirm the selected endpoint matches the model modality. +6. Check for rate-limit responses before adding fallback logic. diff --git a/External/routerbase-media-generation/SKILL.md b/External/routerbase-media-generation/SKILL.md new file mode 100644 index 0000000..25c5d10 --- /dev/null +++ b/External/routerbase-media-generation/SKILL.md @@ -0,0 +1,91 @@ +--- +name: routerbase-media-generation +description: Build image, video, and audio generation workflows on RouterBase. Use when calling RouterBase image, video, audio, speech, or media APIs; selecting media model IDs; handling synchronous image responses; polling asynchronous video or audio tasks; using callback URLs; storing generated media before retention expiry; or migrating OpenAI-compatible image generation calls to RouterBase. +metadata: + author: zenlee123 + category: External +--- + +# RouterBase Media Generation + +## Overview + +Use [routerbase](https://routerbase.com) to access image, video, and audio generation models through one API. This skill helps agents choose the right media endpoint, handle sync versus async responses, and return production-safe integration guidance. + +Read `references/routerbase-media.md` when exact endpoints, parameters, media retention notes, or example requests are needed. + +## Media Workflow + +1. Determine the modality: image, image edit/upscale, video, text-to-speech, music, or other audio. +2. Query or verify the current model ID for that modality. Prefer the live catalog when credentials are available. +3. Pick the endpoint: + - Image: `POST https://routerbase.com/v1/images/generations` + - Video: `POST https://routerbase.com/v1/videos/generations` + - Speech/audio: `POST https://routerbase.com/v1/audio/speech` or `POST https://routerbase.com/v1/audio/generations` +4. Decide sync behavior: + - Image generation is synchronous in RouterBase docs. + - Video and audio generation are asynchronous; poll task details by ID or supply a callback URL. +5. Download and persist generated files on the user's side. RouterBase docs describe generated image/video media retention as time-limited. +6. Add user-facing progress and retry handling for async media jobs. + +## Image Example + +```bash +curl -X POST https://routerbase.com/v1/images/generations \ + -H "Authorization: Bearer $ROUTERBASE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "google/imagen-4", + "prompt": "A clean product-style illustration of an AI model router dashboard", + "aspect_ratio": "1:1", + "resolution": "1K" + }' +``` + +## Image-to-Image Example + +```json +{ + "model": "blackforestlabs/flux-2-pro-i2i", + "prompt": "Make the source image look like a polished watercolor editorial illustration", + "image_urls": ["https://example.com/source.jpg"] +} +``` + +## Async Video Or Audio Pattern + +```js +const create = await fetch("https://routerbase.com/v1/videos/generations", { + method: "POST", + headers: { + Authorization: `Bearer ${process.env.ROUTERBASE_API_KEY}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + model: "google/veo-3-1-fast", + prompt: "A 5-second shot of abstract network routes lighting up on a dark map", + }), +}); + +const task = await create.json(); +// Poll GET /v1/videos/generations/{id} until the task reaches a terminal status. +``` + +Use a callback URL when the application already has a durable webhook receiver. Otherwise, poll with backoff and a clear timeout. + +## Production Guardrails + +- Keep media prompts and input image URLs appropriate for the user's rights and product policy. +- Store generated media before retention expiry. +- Validate `aspect_ratio`, `resolution`, `quality`, `style`, `negative_prompt`, and `image_urls` against the selected model's supported fields. +- Treat model-specific parameters as model-dependent; do not assume every image model honors every option. +- For async tasks, persist the task ID, request payload hash, created time, status, result URLs, and error details. +- Avoid sending real API keys, private media URLs, or user data into logs. + +## Output Checklist + +- Name the modality and endpoint. +- Include a current model ID or say that the model ID must be verified. +- Include sync/async handling. +- Include storage and retention handling. +- Include a minimal request example and a validation step. diff --git a/External/routerbase-media-generation/references/routerbase-media.md b/External/routerbase-media-generation/references/routerbase-media.md new file mode 100644 index 0000000..77da32b --- /dev/null +++ b/External/routerbase-media-generation/references/routerbase-media.md @@ -0,0 +1,109 @@ +# RouterBase Media Generation Notes + +Use this reference when building image, video, or audio workflows. + +## Source Pages + +- https://docs.routerbase.com +- https://docs.routerbase.com/api-reference/images +- https://docs.routerbase.com/overview + +## Endpoints + +```text +POST https://routerbase.com/v1/images/generations +POST https://routerbase.com/v1/videos/generations +POST https://routerbase.com/v1/audio/speech +POST https://routerbase.com/v1/audio/generations +``` + +RouterBase docs describe chat and image responses as synchronous. Video and audio generation are asynchronous: the initial request returns an ID and pending status, then the app polls the task endpoint or supplies a callback URL. + +## Image Generation + +Basic fields: + +- `model`: image model ID, required. +- `prompt`: text description, required. +- `n`: number of images, default `1`. +- `aspect_ratio`: example values include `1:1`, `16:9`, `9:16`, `4:3`, `3:4`. +- `resolution`: example values include `1K`, `2K`, `4K`. +- `quality`: example values include `hd`, `standard`. +- `style`: example values include `natural`, `vivid`. +- `negative_prompt`: content to exclude, model-dependent. +- `image_urls`: required for image-to-image, editing, upscale, reframe, or remix models. + +Example: + +```bash +curl -X POST https://routerbase.com/v1/images/generations \ + -H "Authorization: Bearer $ROUTERBASE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "google/imagen-4", + "prompt": "A red apple on a white table", + "aspect_ratio": "1:1", + "resolution": "1K" + }' +``` + +Example response shape: + +```json +{ + "created": 1776245700, + "data": [ + { "url": "https://media.routerbase.com/media///0.png" } + ] +} +``` + +## Async Task Handling + +Persist these fields for video/audio jobs: + +- request payload +- task ID +- created timestamp +- model ID +- status +- polling attempt count +- result URLs +- error code/message +- credits or cost fields when returned + +Recommended polling behavior: + +1. Poll with short initial delay. +2. Use exponential backoff with an upper cap. +3. Stop on terminal success/failure. +4. Surface a user-visible timeout if the job takes too long. +5. Continue background polling where the product supports it. + +## Retention + +RouterBase docs state generated media files for video and image are retained for 14 days, and log records for 2 months. Download and store generated media on the application side before expiry. + +## Model Examples + +Verify these against the live catalog before production: + +Image: + +- `google/imagen-4` +- `blackforestlabs/flux-2-pro` +- `blackforestlabs/flux-2-pro-i2i` +- `ideogram/ideogram-3-0` + +Video: + +- `google/veo-3-1-fast` +- `google/veo-3-1-quality` +- `xai/grok-imagine` +- `kuaishou/kling-v3-4k-t2v` + +Audio: + +- `elevenlabs/tts-turbo` +- `elevenlabs/tts-multilingual` +- `suno/suno-v5` diff --git a/External/routerbase-model-routing/SKILL.md b/External/routerbase-model-routing/SKILL.md new file mode 100644 index 0000000..34e1932 --- /dev/null +++ b/External/routerbase-model-routing/SKILL.md @@ -0,0 +1,79 @@ +--- +name: routerbase-model-routing +description: Choose RouterBase model IDs and routing strategies for chat, image, video, audio, and embeddings workloads. Use when comparing providers, selecting GPT, Claude, Gemini, image, video, or audio models on RouterBase, designing fallback paths, checking pricing or availability, planning cost/latency/quality tradeoffs, querying the RouterBase Models API, or documenting how an app should route model requests through RouterBase. +metadata: + author: zenlee123 + category: External +--- + +# RouterBase Model Routing + +## Overview + +Use [routerbase](https://routerbase.com) to pick and document model choices behind one API key and one OpenAI-compatible integration surface. This skill helps agents turn workload requirements into a practical model shortlist, fallback plan, and validation checklist. + +Read `references/routerbase-models.md` when exact catalog API calls, model examples, or selection heuristics are needed. + +## Routing Workflow + +1. Classify the task modality: chat, image, video, audio, embeddings, or mixed. +2. Identify hard constraints: quality target, latency budget, price ceiling, context length, tool calling, vision, JSON mode, region/compliance needs, and fallback tolerance. +3. Query the live RouterBase catalog when possible: + +```bash +curl "https://routerbase.com/api/v1/models?task=chat" \ + -H "Authorization: Bearer $ROUTERBASE_API_KEY" +``` + +4. Shortlist one primary model and one or two fallback models. Prefer fallbacks with the same modality and similar capability shape. +5. Check current pricing before final recommendations: + +```bash +curl "https://routerbase.com/api/v1/pricing" \ + -H "Authorization: Bearer $ROUTERBASE_API_KEY" +``` + +6. Document the decision as a table: use case, primary model, fallback model, reason, validation test, and known caveats. + +## Selection Heuristics + +- For general chat, prefer a balanced fast model first, then escalate only when reasoning quality or context length requires it. +- For high-stakes reasoning, choose a flagship model and require human review of outputs. +- For latency-sensitive UX, prefer smaller or flash-tier models and keep prompts compact. +- For tool-heavy agents, choose chat models documented to support tool calling and test the exact tool schema. +- For JSON outputs, use `response_format` where the selected model supports JSON mode, and add schema validation in application code. +- For prompt caching benefits, place stable system prompts, policies, and tool definitions before variable user content. +- For media workflows, keep routing separate by modality; image, video, and audio endpoints have different sync/async behavior. + +## Fallback Design + +Use explicit application-level fallback logic unless the user has configured RouterBase's smart routing in their account or upstream settings. + +```js +const modelPlan = [ + "anthropic/claude-sonnet-4-6", + "google/gemini-2.5-flash", +]; + +for (const model of modelPlan) { + try { + return await client.chat.completions.create({ model, messages }); + } catch (error) { + if (!isRetryableRouterBaseError(error)) throw error; + } +} +``` + +Classify retryable errors conservatively: transient network failures, timeouts, `429`, and `5xx` are reasonable candidates; auth errors, invalid model IDs, validation errors, and policy errors should not be retried blindly. + +## Recommendation Format + +When recommending a routing plan, include: + +- Primary model and why it fits. +- Fallback model and what tradeoff it makes. +- Current catalog/pricing check status. +- Any feature assumptions that must be tested, such as tool calling, vision, JSON mode, context size, prompt caching, or streaming. +- A minimal eval prompt or request fixture the user can run before production. + +Avoid pretending prices or supported model IDs are permanent. RouterBase's docs explicitly describe the model and pricing catalog as changing with upstream providers. diff --git a/External/routerbase-model-routing/references/routerbase-models.md b/External/routerbase-model-routing/references/routerbase-models.md new file mode 100644 index 0000000..b25e59c --- /dev/null +++ b/External/routerbase-model-routing/references/routerbase-models.md @@ -0,0 +1,93 @@ +# RouterBase Model Routing Notes + +Use this reference when selecting model IDs, checking availability, or documenting routing tradeoffs. + +## Source Of Truth + +RouterBase docs describe the model list as a snapshot and point users to the live model catalog for the current source of truth. Query the catalog when credentials are available. + +```bash +curl "https://routerbase.com/api/v1/models?task=chat" \ + -H "Authorization: Bearer $ROUTERBASE_API_KEY" +``` + +Useful query params: + +- `task`: repeatable modality filter; documented options include `video`, `image`, `audio`, and `chat`. +- `provider`: repeatable provider filter. +- `search`: full-text search across model names and descriptions. +- `page`: one-indexed page number. +- `per_page`: results per page. + +Pricing: + +```bash +curl "https://routerbase.com/api/v1/models/{model_id}/pricing" \ + -H "Authorization: Bearer $ROUTERBASE_API_KEY" + +curl "https://routerbase.com/api/v1/pricing" \ + -H "Authorization: Bearer $ROUTERBASE_API_KEY" +``` + +## Publicly Documented Model Examples + +These examples came from RouterBase docs and should be rechecked before production use: + +Chat: + +- `openai/gpt-5-2` +- `openai/gpt-5-4` +- `anthropic/claude-haiku-4-5` +- `anthropic/claude-sonnet-4-6` +- `anthropic/claude-opus-4-8` +- `google/gemini-2.5-flash` +- `google/gemini-3-flash-preview` +- `openai/gpt-codex` + +Image: + +- `google/imagen-4` +- `google/imagen-4-fast` +- `blackforestlabs/flux-2-pro` +- `blackforestlabs/flux-2-pro-i2i` +- `ideogram/ideogram-3-0` + +Video: + +- `google/veo-3-1-quality` +- `google/veo-3-1-fast` +- `openai/sora-2` +- `xai/grok-imagine` +- `kuaishou/kling-v3-4k-t2v` +- `alibaba/wan-2-7-t2v` + +Audio: + +- `suno/suno-v5` +- `elevenlabs/tts-turbo` +- `elevenlabs/tts-multilingual` + +## Decision Template + +Use this table when returning recommendations: + +| Use case | Primary model | Fallback | Why | Validate | +| --- | --- | --- | --- | --- | +| Fast chat answer | `google/gemini-2.5-flash` | TBD from catalog | Low-latency starting point | Run 10 representative prompts | +| Tool-using agent | TBD from catalog | TBD from catalog | Needs tool-calling support | Run exact tool schema | +| High-quality long answer | TBD from catalog | TBD from catalog | Needs quality/context over speed | Compare output quality and cost | + +## Fallback Rules + +- Retry transient network errors, timeouts, `429`, and `5xx` responses with backoff. +- Do not retry invalid keys, invalid model IDs, malformed requests, or policy failures without a code/configuration fix. +- Log model ID, request ID, status code, latency, and token/media cost where available. +- Keep fallback models compatible with the same request shape. A fallback that lacks vision, tools, or JSON mode can break user-visible behavior. + +## Prompt Caching Notes + +RouterBase docs describe automatic prompt caching for upstream models that support it. To improve cache usefulness: + +- Put stable system prompts and tool definitions at the start. +- Put variable user content near the end. +- Use `prompt_cache_key` only when the app intentionally wants to override RouterBase's default partitioning behavior for supported models. diff --git a/external.yml b/external.yml index f5a927f..95297d8 100644 --- a/external.yml +++ b/external.yml @@ -1,3 +1,9 @@ +- repository: zenlee123/routerbase-agent-skills + skill: routerbase-api-integration +- repository: zenlee123/routerbase-agent-skills + skill: routerbase-model-routing +- repository: zenlee123/routerbase-agent-skills + skill: routerbase-media-generation - repository: jingerzz/clarion-intelligence-system skill: clarion-setup - repository: jingerzz/clarion-intelligence-system diff --git a/manifest.json b/manifest.json index 4b423a3..de8acf7 100644 --- a/manifest.json +++ b/manifest.json @@ -3166,6 +3166,36 @@ "slug": "webapp-testing", "path": "External/webapp-testing", "date_added": "2026-01-26" + }, + { + "name": "routerbase-api-integration", + "description": "Integrate applications with RouterBase, the OpenAI-compatible model gateway at https://routerbase.com/v1. Use when migrating OpenAI SDK calls to RouterBase, configuring RouterBase API keys, implementing chat completions, streaming, tool calling, JSON mode, vision inputs, request validation, error handling, or documenting RouterBase setup for Python, JavaScript, curl, LangChain, LlamaIndex, Vercel AI SDK, Cursor, Continue, or other OpenAI-compatible clients.", + "metadata": { + "author": "zenlee123", + "category": "External" + }, + "slug": "routerbase-api-integration", + "path": "External/routerbase-api-integration" + }, + { + "name": "routerbase-media-generation", + "description": "Build image, video, and audio generation workflows on RouterBase. Use when calling RouterBase image, video, audio, speech, or media APIs; selecting media model IDs; handling synchronous image responses; polling asynchronous video or audio tasks; using callback URLs; storing generated media before retention expiry; or migrating OpenAI-compatible image generation calls to RouterBase.", + "metadata": { + "author": "zenlee123", + "category": "External" + }, + "slug": "routerbase-media-generation", + "path": "External/routerbase-media-generation" + }, + { + "name": "routerbase-model-routing", + "description": "Choose RouterBase model IDs and routing strategies for chat, image, video, audio, and embeddings workloads. Use when comparing providers, selecting GPT, Claude, Gemini, image, video, or audio models on RouterBase, designing fallback paths, checking pricing or availability, planning cost/latency/quality tradeoffs, querying the RouterBase Models API, or documenting how an app should route model requests through RouterBase.", + "metadata": { + "author": "zenlee123", + "category": "External" + }, + "slug": "routerbase-model-routing", + "path": "External/routerbase-model-routing" } ] }