mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-31 04:12:10 +03:00
merge(F9a): preserve curated content from 18 old SKILL.md via markers + archive
This commit is contained in:
diegosouzapw
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: omniroute-a2a
|
||||
description: OmniRoute exposes an A2A (Agent-to-Agent) JSON-RPC 2.0 server with 5 skills (smart-routing, quota-management, provider-discovery, cost-analysis, health-report). Use when the user wants OmniRoute to act as an agent peer in an A2A network or multi-agent pipeline.
|
||||
---
|
||||
|
||||
# OmniRoute — A2A Protocol
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
OmniRoute publishes an Agent Card at `/.well-known/agent.json` and accepts
|
||||
JSON-RPC 2.0 calls at `/a2a`.
|
||||
|
||||
## Discovery
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/.well-known/agent.json
|
||||
```
|
||||
|
||||
Returns Agent Card with skills, endpoints, auth scheme.
|
||||
|
||||
## Available skills
|
||||
|
||||
| Skill | Purpose |
|
||||
| -------------------- | ----------------------------------------------------------------------------------- |
|
||||
| `smart-routing` | Given a prompt, recommends best provider/model combo |
|
||||
| `quota-management` | Reports quota balance for given provider/account |
|
||||
| `provider-discovery` | Lists providers matching capability filters (vision, JSON mode, tools, max-context) |
|
||||
| `cost-analysis` | Estimates cost for a given request shape |
|
||||
| `health-report` | Returns system health (circuit states, latencies, errors) |
|
||||
|
||||
## Call example (JSON-RPC 2.0)
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/a2a \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "tasks/send",
|
||||
"params": {
|
||||
"skillId": "smart-routing",
|
||||
"input": { "prompt_length": 4000, "tools": true, "vision": false }
|
||||
},
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
## Response shape
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"result": {
|
||||
"taskId": "...",
|
||||
"status": "completed",
|
||||
"output": { "recommended_combo": "...", "reasoning": "..." }
|
||||
},
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `-32600` → invalid request (bad JSON-RPC envelope)
|
||||
- `-32601` → method not found (check `method` field)
|
||||
- `-32602` → invalid params (check `skillId` against Agent Card)
|
||||
- `401` → missing/invalid `OMNIROUTE_KEY`
|
||||
|
||||
## Reference
|
||||
|
||||
Full docs: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/A2A-SERVER.md
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: omniroute-chat
|
||||
description: Chat / code generation via OmniRoute using OpenAI /v1/chat/completions or Anthropic /v1/messages format with SSE streaming, auto-fallback combos, RTK token saver, and 207+ providers. Use when the user wants to ask an LLM, generate code, summarize text, or run prompts through OmniRoute.
|
||||
---
|
||||
|
||||
# OmniRoute — Chat
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Endpoints
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/chat/completions` — OpenAI format
|
||||
- `POST $OMNIROUTE_URL/v1/messages` — Anthropic Messages format
|
||||
- `POST $OMNIROUTE_URL/v1/responses` — OpenAI Responses API
|
||||
|
||||
## Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models | jq '.data[].id'
|
||||
```
|
||||
|
||||
Combos (e.g. `auto`, `cost-optimized`, `subscription`) auto-fallback through multiple providers.
|
||||
|
||||
## OpenAI format example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/chat/completions \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"messages": [{"role": "user", "content": "Refactor this function"}],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
## Anthropic format example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/messages \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"max_tokens": 4096,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}'
|
||||
```
|
||||
|
||||
## Tool use
|
||||
|
||||
Supports OpenAI `tools` array and Anthropic `tools` block. Tool results
|
||||
auto-compressed via RTK (47 filters: git-diff, grep, test-jest, terraform-plan,
|
||||
docker-logs, etc.) — 20-40% token savings. Disable per-request with
|
||||
`X-Omniroute-Rtk: off` header.
|
||||
|
||||
## Reasoning / thinking
|
||||
|
||||
Anthropic extended thinking and OpenAI Responses reasoning blocks are forwarded
|
||||
verbatim. Cached automatically via reasoning cache.
|
||||
|
||||
## Errors
|
||||
|
||||
- `401` → invalid API key
|
||||
- `400 invalid_model` → model not in registry; check `/v1/models`
|
||||
- `503 circuit_open` → provider circuit breaker tripped; retry later or use combo
|
||||
- `429 rate_limited` → honor `Retry-After`; consider using a combo for auto-fallback
|
||||
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: omniroute-cli-admin
|
||||
description: Manage the OmniRoute server lifecycle via CLI — start/stop/restart, non-interactive setup, diagnostics (omniroute doctor), backup/restore, autostart, and tunnel management. Use when the user wants to operate the OmniRoute server, automate provisioning, or troubleshoot the runtime.
|
||||
---
|
||||
|
||||
# OmniRoute — CLI Admin
|
||||
|
||||
Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
|
||||
|
||||
## Server lifecycle
|
||||
|
||||
```bash
|
||||
omniroute # Start server (default port 20128)
|
||||
omniroute serve # Explicit alias
|
||||
omniroute --port 3000 # Override port
|
||||
omniroute --no-open # Don't auto-open browser
|
||||
omniroute --mcp # Start as MCP server (stdio transport)
|
||||
|
||||
omniroute stop # Stop the running server
|
||||
omniroute restart # Restart the server
|
||||
|
||||
omniroute dashboard # Open dashboard in browser
|
||||
omniroute open # Alias for dashboard
|
||||
omniroute status # Runtime status (uptime, requests, providers)
|
||||
```
|
||||
|
||||
## Setup & provisioning
|
||||
|
||||
### Interactive wizard
|
||||
|
||||
```bash
|
||||
omniroute setup # Step-by-step interactive setup
|
||||
```
|
||||
|
||||
### Non-interactive (CI / Docker)
|
||||
|
||||
```bash
|
||||
omniroute setup --non-interactive \
|
||||
--password 'admin-password' \
|
||||
--add-provider \
|
||||
--provider openai \
|
||||
--api-key 'sk-...' \
|
||||
--test-provider
|
||||
```
|
||||
|
||||
Environment variables for non-interactive setup:
|
||||
|
||||
| Variable | Purpose |
|
||||
| ----------------------------- | -------------------------------------------- |
|
||||
| `OMNIROUTE_SETUP_PASSWORD` | Admin password (≥8 chars) |
|
||||
| `OMNIROUTE_PROVIDER` | Provider id (e.g. `openai`, `anthropic`) |
|
||||
| `OMNIROUTE_PROVIDER_NAME` | Display name for the connection |
|
||||
| `OMNIROUTE_PROVIDER_BASE_URL` | Optional OpenAI-compatible base URL override |
|
||||
| `OMNIROUTE_API_KEY` | Provider API key |
|
||||
| `OMNIROUTE_DEFAULT_MODEL` | Optional default model |
|
||||
| `DATA_DIR` | Override OmniRoute data directory |
|
||||
|
||||
## Diagnostics
|
||||
|
||||
```bash
|
||||
omniroute doctor # Full health check
|
||||
omniroute doctor --json # Machine-readable JSON
|
||||
omniroute doctor --no-liveness # Skip HTTP health probe
|
||||
omniroute doctor --host 0.0.0.0 # Override liveness host
|
||||
omniroute doctor --liveness-url <url> # Full URL override
|
||||
```
|
||||
|
||||
Checks performed: Config, Database, Storage/encryption, Port, Node runtime, Native binary (better-sqlite3), Memory, Server liveness.
|
||||
|
||||
Exit code is non-zero if any check fails — useful in CI:
|
||||
|
||||
```bash
|
||||
omniroute doctor --json | jq '.checks[] | select(.status=="fail")'
|
||||
```
|
||||
|
||||
## Backup & restore
|
||||
|
||||
```bash
|
||||
omniroute backup # Snapshot config + SQLite DB to ~/.omniroute/backups/
|
||||
omniroute restore # Restore from a previous snapshot (interactive picker)
|
||||
```
|
||||
|
||||
## Autostart (system tray / startup)
|
||||
|
||||
```bash
|
||||
omniroute autostart enable # Register OmniRoute as a system startup item
|
||||
omniroute autostart disable # Remove startup registration
|
||||
omniroute autostart status # Show current autostart state
|
||||
```
|
||||
|
||||
On Linux: creates a **systemd user service** (`~/.config/systemd/user/omniroute.service`) and enables **linger** so the service can start after reboot without a graphical login; on desktop sessions it also adds an XDG autostart entry with `--tray`. On macOS: LaunchAgent plist. On Windows: registry startup entry.
|
||||
|
||||
## Tunnels (public URL)
|
||||
|
||||
Expose a local OmniRoute instance via a secure tunnel:
|
||||
|
||||
```bash
|
||||
omniroute tunnel list # List active tunnels
|
||||
omniroute tunnel create cloudflare # Start a Cloudflare Tunnel (free)
|
||||
omniroute tunnel create tailscale # Start a Tailscale funnel
|
||||
omniroute tunnel create ngrok # Start an ngrok tunnel
|
||||
omniroute tunnel stop <id> # Stop a running tunnel
|
||||
```
|
||||
|
||||
The tunnel URL is printed and can be used as `OMNIROUTE_BASE_URL` from remote machines.
|
||||
|
||||
## Config & environment
|
||||
|
||||
```bash
|
||||
omniroute config show # Display current effective configuration
|
||||
omniroute env show # List all OmniRoute environment variables
|
||||
omniroute env get <KEY> # Get a single env var value
|
||||
omniroute env set <KEY> <value> # Set an env var (temporary — until restart)
|
||||
```
|
||||
|
||||
## Recovery
|
||||
|
||||
```bash
|
||||
omniroute reset-password # Reset the admin password interactively
|
||||
omniroute reset-encrypted-columns # Dry-run: show encrypted credential columns
|
||||
omniroute reset-encrypted-columns --force # Null out encrypted credentials in SQLite
|
||||
```
|
||||
|
||||
Use `reset-encrypted-columns --force` only if `STORAGE_ENCRYPTION_KEY` was lost and you need to re-enter all provider API keys.
|
||||
|
||||
## Logs
|
||||
|
||||
```bash
|
||||
omniroute logs # Stream live request logs
|
||||
omniroute logs --json # JSON log entries
|
||||
omniroute logs --search <term> # Filter by term
|
||||
omniroute logs --follow # Tail mode (keep streaming)
|
||||
```
|
||||
|
||||
## Update
|
||||
|
||||
```bash
|
||||
omniroute update # Check for a newer version and prompt to update
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `doctor` shows `STORAGE_ENCRYPTION_KEY missing` → set the key in `.env` or run `reset-encrypted-columns --force` to wipe and re-enter credentials
|
||||
- `doctor` reports native binary fail → `npm rebuild better-sqlite3` in the OmniRoute app directory
|
||||
- `tunnel create cloudflare` hangs → ensure `cloudflared` is installed: `brew install cloudflare/cloudflare/cloudflared`
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
name: omniroute-cli-cloud
|
||||
description: Control OmniRoute cloud agents (OpenAI Codex, Devin, Jules) from the CLI — create tasks, track status, approve plans, send messages, and manage sources. Use when the user wants to automate cloud coding agent workflows via the terminal.
|
||||
---
|
||||
|
||||
# OmniRoute — CLI Cloud Agents
|
||||
|
||||
Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
|
||||
|
||||
## Supported agents
|
||||
|
||||
| Agent | ID | Auth required |
|
||||
| -------------- | ------- | -------------- |
|
||||
| OpenAI Codex | `codex` | OpenAI API key |
|
||||
| Devin | `devin` | Devin API key |
|
||||
| Jules (Google) | `jules` | Google OAuth |
|
||||
|
||||
## Authenticate an agent
|
||||
|
||||
```bash
|
||||
omniroute cloud codex auth # Set / refresh Codex API key
|
||||
omniroute cloud devin auth # Set / refresh Devin API key
|
||||
omniroute cloud jules auth # OAuth login for Jules (opens browser)
|
||||
```
|
||||
|
||||
## List all agents
|
||||
|
||||
```bash
|
||||
omniroute cloud agents # Show all configured cloud agents + status
|
||||
omniroute cloud agents --json
|
||||
```
|
||||
|
||||
## Create a task
|
||||
|
||||
```bash
|
||||
omniroute cloud codex task create \
|
||||
--title "Add OAuth to the auth module" \
|
||||
--prompt "Implement Google OAuth 2.0 login in src/auth/oauth.ts"
|
||||
|
||||
omniroute cloud codex task create \
|
||||
--title "Fix test failures" \
|
||||
--prompt-file ./task-description.md # Read prompt from a file
|
||||
```
|
||||
|
||||
Same syntax for `devin` and `jules`:
|
||||
|
||||
```bash
|
||||
omniroute cloud devin task create --title "..." --prompt "..."
|
||||
omniroute cloud jules task create --title "..." --prompt "..."
|
||||
```
|
||||
|
||||
## List tasks
|
||||
|
||||
```bash
|
||||
omniroute cloud codex task list # All Codex tasks (table)
|
||||
omniroute cloud codex task list --json # JSON output
|
||||
```
|
||||
|
||||
## Get task details
|
||||
|
||||
```bash
|
||||
omniroute cloud codex task get <taskId> # Full task record
|
||||
omniroute cloud codex task status <taskId> # Status + progress only
|
||||
```
|
||||
|
||||
Task status values: `running`, `completed`, `failed`, `cancelled`.
|
||||
|
||||
## Approve a plan
|
||||
|
||||
Devin and Jules may pause for plan approval before writing code:
|
||||
|
||||
```bash
|
||||
omniroute cloud devin task approve <taskId> # Approve the proposed plan
|
||||
omniroute cloud jules task approve <taskId>
|
||||
```
|
||||
|
||||
## Send a message to a running task
|
||||
|
||||
```bash
|
||||
omniroute cloud codex task message <taskId> "Focus on the backend only, skip the UI"
|
||||
```
|
||||
|
||||
## List task sources (files touched)
|
||||
|
||||
```bash
|
||||
omniroute cloud codex task sources <taskId> # Files changed / created by the task
|
||||
```
|
||||
|
||||
## Cancel a task
|
||||
|
||||
```bash
|
||||
omniroute cloud codex task cancel <taskId>
|
||||
omniroute cloud devin task cancel <taskId>
|
||||
```
|
||||
|
||||
## Typical workflow
|
||||
|
||||
```bash
|
||||
# 1. Authenticate
|
||||
omniroute cloud codex auth
|
||||
|
||||
# 2. Create a task
|
||||
TASK_ID=$(omniroute cloud codex task create \
|
||||
--title "Refactor auth module" \
|
||||
--prompt "Extract JWT logic to src/auth/jwt.ts" \
|
||||
--output json | jq -r '.id')
|
||||
|
||||
# 3. Poll status
|
||||
omniroute cloud codex task status $TASK_ID
|
||||
|
||||
# 4. View touched files when complete
|
||||
omniroute cloud codex task sources $TASK_ID
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `auth required` → run `omniroute cloud <agent> auth` before any task commands
|
||||
- `task create` fails with 402 → agent billing limit reached; check your Codex/Devin/Jules account
|
||||
- `task approve` fails with 404 → task does not have a pending plan; check status first
|
||||
- `jules auth` browser flow fails → ensure Google account has Jules access; try `omniroute cloud jules auth` again
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: omniroute-cli-eval
|
||||
description: Run and manage OmniRoute eval suites from the CLI — create suites, run benchmarks, watch live results, view scorecards, and compare model performance. Use when the user wants to benchmark models, validate quality regressions, or automate LLM evals in CI.
|
||||
---
|
||||
|
||||
# OmniRoute — CLI Evals
|
||||
|
||||
Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
|
||||
|
||||
## What are evals?
|
||||
|
||||
Evals are automated test suites that score LLM outputs against expected answers or rubrics. OmniRoute stores suites and run results in its local database.
|
||||
|
||||
## Eval suites
|
||||
|
||||
```bash
|
||||
omniroute eval suites list # List all eval suites
|
||||
omniroute eval suites list --json # JSON output
|
||||
|
||||
omniroute eval suites get <suiteId> # Full suite definition
|
||||
```
|
||||
|
||||
### Create a suite
|
||||
|
||||
```bash
|
||||
omniroute eval suites create \
|
||||
--name "code-quality" \
|
||||
--rubric "exact-match" \
|
||||
--samples-file ./samples.jsonl # JSONL: {input, expected_output}
|
||||
```
|
||||
|
||||
Rubric options: `exact-match`, `contains`, `llm-judge`, `regex`.
|
||||
|
||||
`--samples-file` format (one JSON object per line):
|
||||
|
||||
```jsonl
|
||||
{"input": "What is 2+2?", "expected_output": "4"}
|
||||
{"input": "Translate 'hello' to Spanish", "expected_output": "hola"}
|
||||
```
|
||||
|
||||
## Run an eval
|
||||
|
||||
```bash
|
||||
omniroute eval suites run <suiteId> \
|
||||
--model claude-sonnet-4-6 # Run suite against a specific model
|
||||
|
||||
omniroute eval suites run <suiteId> \
|
||||
--model gpt-4o \
|
||||
--watch # Live TUI progress (EvalWatch)
|
||||
```
|
||||
|
||||
The run is asynchronous. Use `--watch` for a live terminal dashboard or poll manually:
|
||||
|
||||
```bash
|
||||
RUN_ID=$(omniroute eval suites run <suiteId> --model claude-sonnet-4-6 --output json | jq -r '.id')
|
||||
omniroute eval get $RUN_ID
|
||||
```
|
||||
|
||||
## Manage runs
|
||||
|
||||
```bash
|
||||
omniroute eval list # List all eval runs
|
||||
omniroute eval list --json
|
||||
|
||||
omniroute eval get <runId> # Run details (status, model, score)
|
||||
omniroute eval results <runId> # Per-sample results
|
||||
omniroute eval scorecard <runId> # Full scorecard with pass/fail per sample
|
||||
omniroute eval cancel <runId> # Cancel a running eval
|
||||
```
|
||||
|
||||
## Scorecard output
|
||||
|
||||
```bash
|
||||
omniroute eval scorecard <runId> --output json
|
||||
```
|
||||
|
||||
Response fields per sample:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "sample-1",
|
||||
"score": 0.95,
|
||||
"passed": true,
|
||||
"input": "What is 2+2?",
|
||||
"output": "4",
|
||||
"expected": "4"
|
||||
}
|
||||
```
|
||||
|
||||
## Comparing models
|
||||
|
||||
Run the same suite against multiple models and compare:
|
||||
|
||||
```bash
|
||||
for MODEL in claude-sonnet-4-6 gpt-4o gemini-2.0-flash; do
|
||||
omniroute eval suites run $SUITE_ID --model $MODEL --output json | jq '{model: .model, score: .score}'
|
||||
done
|
||||
```
|
||||
|
||||
## CI integration
|
||||
|
||||
```bash
|
||||
# Run and fail CI if score drops below threshold
|
||||
SCORE=$(omniroute eval suites run $SUITE_ID --model claude-sonnet-4-6 --output json | jq -r '.score')
|
||||
python3 -c "import sys; score=float('$SCORE'); sys.exit(0 if score >= 0.90 else 1)"
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `suites create` fails with `invalid rubric` → use one of: `exact-match`, `contains`, `llm-judge`, `regex`
|
||||
- `suites run` returns `model not found` → verify model ID with `omniroute models --search <name>`
|
||||
- `eval get` shows `status: failed` → check `omniroute logs --search eval` for error details
|
||||
- `scorecard` returns empty results → the run may still be `running`; poll `omniroute eval get <runId>` until `status` is `completed`
|
||||
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: omniroute-cli-providers
|
||||
description: Manage OmniRoute provider connections, API keys, and routing combos via CLI — add/list/test/remove providers, rotate keys, run OAuth flows, list models, and create/switch combos. Use when the user wants to configure providers, manage credentials, or set up routing from the terminal.
|
||||
---
|
||||
|
||||
# OmniRoute — CLI Providers & Keys
|
||||
|
||||
Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
|
||||
|
||||
## Provider catalog (available providers)
|
||||
|
||||
```bash
|
||||
omniroute providers available # Full OmniRoute provider catalog
|
||||
omniroute providers available --search openai # Filter by id, name, alias
|
||||
omniroute providers available --category api-key # Filter by category
|
||||
omniroute providers available --json # Machine-readable JSON
|
||||
```
|
||||
|
||||
Categories: `api-key`, `oauth`, `free`, `local`, `combo`.
|
||||
|
||||
## Configured provider connections
|
||||
|
||||
```bash
|
||||
omniroute providers list # Connections in your DB
|
||||
omniroute providers list --json
|
||||
```
|
||||
|
||||
## Testing connections
|
||||
|
||||
```bash
|
||||
omniroute providers test <id|name> # Test one configured connection
|
||||
omniroute providers test-all # Test every active connection (TUI progress)
|
||||
omniroute providers validate # Local-only structural validation (no HTTP)
|
||||
```
|
||||
|
||||
`test-all` opens an interactive TUI that shows live pass/fail per connection. Use `--json` to get a machine-readable result:
|
||||
|
||||
```bash
|
||||
omniroute providers test-all --json
|
||||
```
|
||||
|
||||
## API key management (OmniRoute keys)
|
||||
|
||||
These manage the OmniRoute API keys issued under **API Manager** — not provider credentials.
|
||||
|
||||
```bash
|
||||
omniroute keys list # List all OmniRoute API keys
|
||||
omniroute keys add <provider> [apiKey] # Add an API key for a provider
|
||||
omniroute keys remove <provider> # Remove an API key
|
||||
omniroute keys regenerate <id> # Regenerate (rotate) a key
|
||||
omniroute keys revoke <id> # Revoke a key (disables it)
|
||||
omniroute keys reveal <id> # Show the full key value
|
||||
omniroute keys usage <id> # Show usage stats for a key
|
||||
|
||||
omniroute keys rotate <id> # Rotate + revoke old key atomically
|
||||
omniroute keys expiration list # List key expiration times
|
||||
```
|
||||
|
||||
### Key policies
|
||||
|
||||
```bash
|
||||
omniroute keys policy show <id> # Show rate-limit / permission policy
|
||||
omniroute keys policy set <id> \
|
||||
--rate-limit 100 \
|
||||
--rate-window minute \
|
||||
--permissions chat,models # Set policy on a key
|
||||
```
|
||||
|
||||
## Models
|
||||
|
||||
```bash
|
||||
omniroute models # List all models (all providers)
|
||||
omniroute models openai # Filter by provider
|
||||
omniroute models --search gpt # Search by name
|
||||
omniroute models --json # JSON output
|
||||
```
|
||||
|
||||
## OAuth providers
|
||||
|
||||
```bash
|
||||
omniroute oauth list # List OAuth-configured providers
|
||||
omniroute oauth login <provider> # Start browser-based OAuth flow
|
||||
omniroute oauth logout <provider> # Revoke OAuth token
|
||||
omniroute oauth status <provider> # Show token state + expiry
|
||||
omniroute oauth refresh <provider> # Force token refresh
|
||||
```
|
||||
|
||||
For OAuth providers (Gemini, Windsurf, Antigravity, etc.) the `login` command opens the OmniRoute dashboard OAuth flow in your browser.
|
||||
|
||||
## Provider nodes (multi-account routing)
|
||||
|
||||
Provider nodes let you attach multiple API keys / accounts to one logical provider for round-robin or failover.
|
||||
|
||||
```bash
|
||||
omniroute nodes list <provider> # List nodes for a provider
|
||||
omniroute nodes add <provider> --api-key <key> # Add a node
|
||||
omniroute nodes remove <provider> <nodeId> # Remove a node
|
||||
omniroute nodes test <provider> <nodeId> # Test one node
|
||||
```
|
||||
|
||||
## Routing combos (CLI)
|
||||
|
||||
Create and manage routing combos from the terminal:
|
||||
|
||||
```bash
|
||||
omniroute combo list # List all combos
|
||||
omniroute combo create <name> \
|
||||
--strategy priority \
|
||||
--targets anthropic/claude-opus-4-7,openai/gpt-4o # Create combo
|
||||
omniroute combo switch <name> # Activate a combo as default
|
||||
omniroute combo delete <name> # Delete a combo
|
||||
omniroute combo suggest --task "code review" # Ask OmniRoute to recommend a combo
|
||||
```
|
||||
|
||||
For the full REST API for combos see [omniroute-routing skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-routing/SKILL.md).
|
||||
|
||||
## Quota & usage
|
||||
|
||||
```bash
|
||||
omniroute quota # Provider quota usage + reset times
|
||||
omniroute usage # Request + token usage summary
|
||||
omniroute cost # Cost breakdown (by provider/model)
|
||||
```
|
||||
|
||||
## Compression (CLI)
|
||||
|
||||
```bash
|
||||
omniroute compression status # Current compression mode + savings stats
|
||||
omniroute compression set --mode rtk # Enable RTK compression
|
||||
omniroute compression set --mode stacked # Enable stacked (RTK + Caveman)
|
||||
omniroute compression set --mode off # Disable compression
|
||||
omniroute compression preview --mode rtk --text "..." # Preview savings for sample text
|
||||
```
|
||||
|
||||
## Health
|
||||
|
||||
```bash
|
||||
omniroute health # Detailed health: circuit breakers, cache, memory
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `providers test <id>` fails with 401 → API key stored for that provider is wrong; use `keys remove` + `keys add` to reset it
|
||||
- `oauth login` opens but doesn't complete → the OAuth token endpoint may be firewalled; use API key auth instead
|
||||
- `combo create` fails with `strategy unknown` → use one of: `priority`, `weighted`, `round-robin`, `fill-first`, `least-used`, `cost-optimized`, `auto`, `random`, `strict-random`, `p2c`, `reset-aware`, `lkgp`, `context-optimized`, `context-relay`
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
name: omniroute-cli
|
||||
description: Entry point for the OmniRoute CLI (omniroute binary) — install, global flags, output formats, environment variables, and index of CLI capability skills. Use when the user wants to control OmniRoute from the terminal, automate workflows, or integrate with CI/CD.
|
||||
---
|
||||
|
||||
# OmniRoute — CLI (Entry Point)
|
||||
|
||||
The `omniroute` binary ships with the OmniRoute server. It is both the server launcher and a full management CLI with 250+ commands across 39 groups.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install -g omniroute # npm registry
|
||||
# or: use the binary bundled with the desktop app
|
||||
```
|
||||
|
||||
Requires Node.js ≥20.20.2, ≥22.22.2, or ≥24.
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
omniroute --version # prints installed version
|
||||
omniroute --help # full command tree
|
||||
```
|
||||
|
||||
## Connection
|
||||
|
||||
Every CLI command that talks to the server reads two values:
|
||||
|
||||
| Source | Variable / Flag |
|
||||
| -------- | ------------------------------------ |
|
||||
| Base URL | `OMNIROUTE_BASE_URL` or `--base-url` |
|
||||
| API key | `OMNIROUTE_API_KEY` or `--api-key` |
|
||||
|
||||
Default base URL: `http://localhost:20128`
|
||||
|
||||
```bash
|
||||
export OMNIROUTE_BASE_URL="http://localhost:20128"
|
||||
export OMNIROUTE_API_KEY="sk-..." # from Dashboard → API Manager
|
||||
```
|
||||
|
||||
For a remote server:
|
||||
|
||||
```bash
|
||||
export OMNIROUTE_BASE_URL="https://your-server.com"
|
||||
```
|
||||
|
||||
## Global flags
|
||||
|
||||
| Flag | Description |
|
||||
| ------------------- | -------------------------------------------------------- |
|
||||
| `--base-url <url>` | Override server URL for this invocation |
|
||||
| `--api-key <key>` | Override API key for this invocation |
|
||||
| `--output <format>` | Output format: `table` (default), `json`, `jsonl`, `csv` |
|
||||
| `--json` | Shorthand for `--output json` |
|
||||
| `--non-interactive` | Disable prompts — for CI / shell scripts |
|
||||
| `--no-open` | Don't auto-open the browser on start |
|
||||
| `--port <n>` | Override default port 20128 |
|
||||
| `--help`, `-h` | Show help for the current command |
|
||||
| `--version`, `-v` | Print the installed version |
|
||||
|
||||
## Output formats
|
||||
|
||||
All listing commands support `--output`:
|
||||
|
||||
```bash
|
||||
omniroute combo list # human-readable table
|
||||
omniroute combo list --output json # JSON array
|
||||
omniroute combo list --output jsonl # one JSON object per line
|
||||
omniroute combo list --output csv # CSV with header row
|
||||
```
|
||||
|
||||
## Quick start: one-shot server + provider setup
|
||||
|
||||
```bash
|
||||
# 1. Start server
|
||||
omniroute
|
||||
|
||||
# 2. (First run) interactive setup wizard
|
||||
omniroute setup
|
||||
|
||||
# 3. Verify everything is healthy
|
||||
omniroute doctor
|
||||
```
|
||||
|
||||
## CLI capability skills
|
||||
|
||||
| Capability | Skill |
|
||||
| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
|
||||
| Server admin + backup | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-admin/SKILL.md |
|
||||
| Provider & key management | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-providers/SKILL.md |
|
||||
| Cloud agents (Codex / Devin / Jules) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-cloud/SKILL.md |
|
||||
| Evals & benchmarking | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-eval/SKILL.md |
|
||||
|
||||
## API skills (REST)
|
||||
|
||||
For direct HTTP usage instead of the CLI, see the [OmniRoute entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md).
|
||||
|
||||
## Errors
|
||||
|
||||
- `Connection refused` → server not running; run `omniroute` or `omniroute serve`
|
||||
- `401 Unauthorized` → wrong or missing API key
|
||||
- `command not found: omniroute` → not in PATH; check `npm root -g` or re-install
|
||||
- `doctor` reports SQLite incompatible → `npm rebuild better-sqlite3` in the app directory
|
||||
@@ -0,0 +1,131 @@
|
||||
---
|
||||
name: omniroute-compression
|
||||
description: Configure OmniRoute token compression to save 60–90% of context tokens. Covers RTK (command/tool output), Caveman (prose), stacked mode (both), and the MCP accessibility-tree filter (browser snapshots). Use when the user wants to reduce costs, fit long sessions into context windows, or speed up AI responses.
|
||||
---
|
||||
|
||||
# OmniRoute — Compression
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Overview
|
||||
|
||||
OmniRoute compresses token payloads before forwarding to providers. No code changes required — set it once, it applies to all requests transparently.
|
||||
|
||||
| Engine | Best for | Typical savings |
|
||||
| ------------------------- | ------------------------------------ | --------------- |
|
||||
| RTK | Terminal / build / test / git output | 60–90% |
|
||||
| Caveman | Human prose, chat history | 46% input |
|
||||
| Stacked (`rtk → caveman`) | Mixed coding sessions | 78–95% |
|
||||
| MCP accessibility filter | Browser/accessibility tool results | 60–80% |
|
||||
|
||||
## Get current settings
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
## Enable RTK (best for coding agents)
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "mode": "rtk", "enabled": true }'
|
||||
```
|
||||
|
||||
## Enable stacked mode (maximum savings)
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mode": "stacked",
|
||||
"enabled": true,
|
||||
"stackedPipeline": ["rtk", "caveman"]
|
||||
}'
|
||||
```
|
||||
|
||||
## Enable Caveman (prose / chat)
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "mode": "standard", "enabled": true }'
|
||||
```
|
||||
|
||||
Caveman intensities: `lite` (safe), `standard` (balanced), `aggressive` (long sessions), `ultra` (context recovery).
|
||||
|
||||
## Preview compression before enabling
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/compression/preview \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mode": "rtk",
|
||||
"text": "$ npm test\n> jest\n\nPASS src/a.test.ts (2.1s)\nPASS src/b.test.ts (1.8s)\n..."
|
||||
}'
|
||||
```
|
||||
|
||||
Response includes `compressed`, `original_length`, `compressed_length`, `savings_pct`.
|
||||
|
||||
## MCP accessibility-tree filter (browser agent use)
|
||||
|
||||
When OmniRoute is used with browser/Playwright MCP tools, it automatically compresses verbose accessibility-tree tool results. Enabled by default; configure thresholds:
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mcpAccessibility": {
|
||||
"enabled": true,
|
||||
"collapseThreshold": 30,
|
||||
"maxTextChars": 50000
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
`collapseThreshold`: collapse sibling lines when ≥ N repeats (default 30).
|
||||
`maxTextChars`: hard truncate after N chars with navigation hint (default 50000).
|
||||
|
||||
## Language packs (Caveman)
|
||||
|
||||
Caveman supports language-aware rules for pt-BR, es, de, fr, ja:
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mode": "standard",
|
||||
"cavemanConfig": {
|
||||
"language": "pt-BR",
|
||||
"autoDetectLanguage": true
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Via MCP
|
||||
|
||||
```
|
||||
omniroute_compression_status → current settings + savings analytics
|
||||
omniroute_compression_configure → update mode/threshold/language
|
||||
omniroute_set_compression_engine → switch engine at runtime
|
||||
```
|
||||
|
||||
## Disable compression
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-d '{ "enabled": false }'
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `400 invalid mode` → use `off`, `lite`, `standard`, `aggressive`, `ultra`, `rtk`, or `stacked`
|
||||
- `400 invalid stackedPipeline` → array must contain valid engine ids (`rtk`, `caveman`)
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: omniroute-embeddings
|
||||
description: Embeddings via OmniRoute using OpenAI /v1/embeddings format with auto-fallback across text-embedding-3-large, Voyage, Cohere, Gemini embeddings, Jina. Use when the user needs vector embeddings for RAG, similarity search, or clustering.
|
||||
---
|
||||
|
||||
# OmniRoute — Embeddings
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Endpoint
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/embeddings`
|
||||
|
||||
## Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/embedding | jq '.data[]'
|
||||
```
|
||||
|
||||
Each entry: `{ id, owned_by, dimensions, max_input_tokens }`.
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/embeddings \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "text-embedding-3-large",
|
||||
"input": ["first text", "second text"],
|
||||
"encoding_format": "float"
|
||||
}'
|
||||
```
|
||||
|
||||
Response: `{ data:[{ embedding:[...], index }], usage:{ prompt_tokens, total_tokens } }`
|
||||
|
||||
## Batch input
|
||||
|
||||
`input` accepts a string or array of strings (up to provider batch limit, typically 2048 items).
|
||||
|
||||
## Errors
|
||||
|
||||
- `400 input_too_long` → input exceeds `max_input_tokens` for this model
|
||||
- `400 invalid_encoding_format` → use `float` or `base64`
|
||||
- `503` → provider unavailable; try another model in `/v1/models/embedding`
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: omniroute-image
|
||||
description: Image generation via OmniRoute using OpenAI /v1/images/generations format with auto-fallback across DALL-E, Stable Diffusion, Flux, Imagen providers. Use when the user wants to generate, edit, or vary images.
|
||||
---
|
||||
|
||||
# OmniRoute — Image Generation
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Endpoints
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/images/generations` — Text-to-image
|
||||
- `POST $OMNIROUTE_URL/v1/images/edits` — Image edit (mask)
|
||||
- `POST $OMNIROUTE_URL/v1/images/variations` — Variations
|
||||
|
||||
## Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/image | jq '.data[]'
|
||||
```
|
||||
|
||||
Returns `{ id, owned_by, sizes:[...], capabilities:[...] }` per model.
|
||||
|
||||
## Generate example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/images/generations \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "dall-e-3",
|
||||
"prompt": "a red bicycle on a wet street, photoreal",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"response_format": "b64_json"
|
||||
}'
|
||||
```
|
||||
|
||||
Response: `{ created, data: [{ url? or b64_json, revised_prompt }] }`
|
||||
|
||||
## Errors
|
||||
|
||||
- `400 invalid_size` → not supported by this model; check `/v1/models/image`
|
||||
- `400 content_policy_violation` → blocked by provider safety
|
||||
- `503` → provider unavailable; try another model in `/v1/models/image`
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: omniroute-mcp
|
||||
description: OmniRoute exposes a built-in MCP (Model Context Protocol) server with 37 tools (chat, embeddings, memory CRUD, skills, providers, routing, audit) over SSE/stdio/HTTP transports. Use when the user wants to add OmniRoute as an MCP server in Claude Desktop, Cursor, Cline, or any MCP-compatible client.
|
||||
---
|
||||
|
||||
# OmniRoute — MCP Server
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Transports
|
||||
|
||||
- **stdio** — local IPC, for Claude Desktop / VS Code extensions
|
||||
- **SSE** — `GET $OMNIROUTE_URL/api/mcp/sse`
|
||||
- **Streamable HTTP** — `POST $OMNIROUTE_URL/api/mcp/stream`
|
||||
|
||||
## Claude Desktop config
|
||||
|
||||
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"omniroute": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "omniroute", "--mcp"],
|
||||
"env": { "OMNIROUTE_KEY": "sk-..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Cursor / VS Code config
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"omniroute": {
|
||||
"url": "http://localhost:20128/api/mcp/sse",
|
||||
"headers": { "Authorization": "Bearer sk-..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Available tools (37 total)
|
||||
|
||||
| Scope | Tools |
|
||||
| --------- | -------------------------------------------------------------------------------------------------- |
|
||||
| health | `omniroute_get_health` |
|
||||
| combos | `omniroute_list_combos`, `omniroute_get_combo_metrics`, `omniroute_switch_combo` |
|
||||
| routing | `omniroute_simulate_route`, `omniroute_best_combo_for_task`, `omniroute_explain_route` |
|
||||
| providers | `omniroute_get_provider_metrics`, `omniroute_check_quota`, `omniroute_route_request` |
|
||||
| budget | `omniroute_set_budget_guard`, `omniroute_set_routing_strategy`, `omniroute_set_resilience_profile` |
|
||||
| testing | `omniroute_test_combo` |
|
||||
| memory | `memory_add`, `memory_search`, `memory_delete` |
|
||||
| skills | `skill_invoke`, `skill_list`, `skill_describe`, `skill_register` |
|
||||
| cache | `omniroute_cache_stats`, `omniroute_cache_flush` |
|
||||
| admin | `omniroute_db_health_check`, `omniroute_sync_pricing`, `omniroute_get_session_snapshot` |
|
||||
|
||||
Full list: `GET $OMNIROUTE_URL/api/mcp/tools`
|
||||
|
||||
## Scopes
|
||||
|
||||
Tools are grouped into 13 scopes (chat-only, memory-readonly, full-admin, etc.).
|
||||
Pass scope name as `--scope` arg or via `X-Omniroute-Scope` header.
|
||||
|
||||
## Reference
|
||||
|
||||
Full docs: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/MCP-SERVER.md
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
name: omniroute-monitoring
|
||||
description: Monitor OmniRoute system health, provider circuit breakers, per-provider latency (p50/p95/p99), quota usage, and set budget guards. Use when the user wants to check if the system is healthy, debug slow providers, manage spend limits, or set up oncall-style monitoring.
|
||||
---
|
||||
|
||||
# OmniRoute — Monitoring & Health
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## System health
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/health \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Returns: uptime, memory, active connections, circuit breaker states, rate limit status, cache stats.
|
||||
|
||||
Unauthenticated quick check:
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/health
|
||||
# → {"ok":true}
|
||||
```
|
||||
|
||||
## Provider circuit breakers
|
||||
|
||||
Circuit breakers prevent traffic from hitting failing providers.
|
||||
|
||||
States: `CLOSED` (normal), `OPEN` (blocked), `HALF_OPEN` (probe mode — auto-recovers).
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/monitoring/health \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Response includes `circuitBreakers` array with per-provider state and `resetAt` timestamp.
|
||||
|
||||
## Per-provider metrics (p50/p95/p99)
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/providers/metrics \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Response shape per provider:
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "anthropic",
|
||||
"requests": 1247,
|
||||
"successRate": 0.994,
|
||||
"latency": { "p50": 820, "p95": 2100, "p99": 3800 },
|
||||
"circuitState": "CLOSED",
|
||||
"tokensUsed": 2847000
|
||||
}
|
||||
```
|
||||
|
||||
## Via MCP (if OmniRoute is your MCP server)
|
||||
|
||||
```
|
||||
omniroute_get_health → full system health snapshot
|
||||
omniroute_get_provider_metrics → p50/p95/p99 + circuit state per provider
|
||||
omniroute_get_session_snapshot → cost, tokens, errors for current session
|
||||
omniroute_check_quota → quota balance + percent remaining + reset time
|
||||
omniroute_db_health_check → diagnose + auto-repair database drift
|
||||
```
|
||||
|
||||
## Quota check
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/quota \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Returns used/total tokens and requests per provider/account, with `resetAt` timestamps.
|
||||
|
||||
## Budget guard (spend limit)
|
||||
|
||||
Set a session spending limit that degrades or blocks requests when hit:
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/budget/guard \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"limitUsd": 5.00,
|
||||
"action": "degrade",
|
||||
"degradeTo": "openai/gpt-4o-mini"
|
||||
}'
|
||||
```
|
||||
|
||||
`action` options:
|
||||
|
||||
- `degrade` — switch to a cheaper model when limit is hit
|
||||
- `block` — return 429 when limit is hit
|
||||
- `alert` — continue but add `X-Budget-Warning` header
|
||||
|
||||
## MCP audit log
|
||||
|
||||
OmniRoute logs every MCP tool call to `mcp_audit` table. Query via API:
|
||||
|
||||
```bash
|
||||
curl "$OMNIROUTE_URL/api/mcp/status" \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Returns: server status, heartbeat, recent audit activity summary.
|
||||
|
||||
## Errors
|
||||
|
||||
- `503` on health endpoint → OmniRoute is starting up; retry in 5s
|
||||
- Circuit breaker `OPEN` → provider is temporarily blocked; check `resetAt` to know when it auto-recovers
|
||||
- `429 budget_exceeded` → budget guard limit reached; raise limit or wait for reset
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
name: omniroute-routing
|
||||
description: Create and configure OmniRoute routing combos, choose from 14 strategies (priority, weighted, auto, round-robin, cost-optimized, etc.), activate Auto-combo 9-factor scoring, and set up fallback chains. Use when the user wants to configure multi-provider routing, load balancing, or cost-optimized model selection.
|
||||
---
|
||||
|
||||
# OmniRoute — Routing & Combos
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## What is a combo?
|
||||
|
||||
A combo is a named group of providers/models with a routing strategy. All requests through a combo are automatically distributed, failed-over, and load-balanced — the caller uses a single model ID like `my-combo`.
|
||||
|
||||
## List existing combos
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/combos \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Response includes `id`, `name`, `strategy`, `enabled`, and per-target stats.
|
||||
|
||||
## Create a combo
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/combos \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "my-combo",
|
||||
"strategy": "priority",
|
||||
"targets": [
|
||||
{ "provider": "anthropic", "model": "claude-opus-4-7", "weight": 1 },
|
||||
{ "provider": "openai", "model": "gpt-4o", "weight": 1 }
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## 14 routing strategies
|
||||
|
||||
| Strategy | Description |
|
||||
| ------------------- | -------------------------------------------------- |
|
||||
| `priority` | Always use target[0]; fall back on error |
|
||||
| `weighted` | Distribute by weight percentage |
|
||||
| `round-robin` | Rotate targets in order |
|
||||
| `fill-first` | Fill quota of target[0] before spilling |
|
||||
| `least-used` | Route to target with fewest active requests |
|
||||
| `cost-optimized` | Pick cheapest target for the token estimate |
|
||||
| `auto` | 9-factor scoring: cost + latency + quota + circuit |
|
||||
| `random` | Uniform random selection |
|
||||
| `strict-random` | Random without repeating until all used |
|
||||
| `p2c` | Power-of-2-choices: sample 2, pick better |
|
||||
| `reset-aware` | Prefer targets near quota reset time |
|
||||
| `lkgp` | Last-known-good-provider sticky routing |
|
||||
| `context-optimized` | Pick best model for context length |
|
||||
| `context-relay` | Chain models for very long contexts |
|
||||
|
||||
## Auto-combo (recommended for production)
|
||||
|
||||
Auto-combo scores each candidate on 9 factors every request:
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/combos \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "prod-auto",
|
||||
"strategy": "auto",
|
||||
"targets": [
|
||||
{ "provider": "anthropic", "model": "claude-sonnet-4-6" },
|
||||
{ "provider": "openai", "model": "gpt-4o-mini" },
|
||||
{ "provider": "google", "model": "gemini-2.0-flash" }
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Then call it with:
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/chat/completions \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "model": "prod-auto", "messages": [{ "role": "user", "content": "Hello" }] }'
|
||||
```
|
||||
|
||||
## Activate / deactivate a combo
|
||||
|
||||
```bash
|
||||
# Activate
|
||||
curl -X PUT $OMNIROUTE_URL/api/combos/{id}/toggle \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-d '{ "enabled": true }'
|
||||
```
|
||||
|
||||
## Get combo metrics
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/combos/{id}/metrics \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Returns p50/p95/p99 latency, success rate, cost, and per-target breakdown.
|
||||
|
||||
## Simulate routing (dry run)
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/routing/simulate \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "comboId": "{id}", "messages": [{ "role": "user", "content": "test" }] }'
|
||||
```
|
||||
|
||||
Returns which provider would be selected and why — no actual API call is made.
|
||||
|
||||
## Via MCP (if OmniRoute is your MCP server)
|
||||
|
||||
```
|
||||
omniroute_list_combos → list all combos
|
||||
omniroute_switch_combo → enable/disable a combo
|
||||
omniroute_set_routing_strategy → change strategy at runtime
|
||||
omniroute_simulate_route → dry-run routing decision
|
||||
omniroute_best_combo_for_task → get recommendation by task type
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `404 combo not found` → check `id` from `/api/combos`
|
||||
- `400 invalid strategy` → use one of the 14 strategies above
|
||||
- `409 name conflict` → combo name already exists
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: omniroute-stt
|
||||
description: Speech-to-text via OmniRoute using OpenAI /v1/audio/transcriptions format with auto-fallback across Whisper, AssemblyAI, Deepgram, Azure STT. Use when the user wants transcription of audio files or real-time speech recognition.
|
||||
---
|
||||
|
||||
# OmniRoute — Speech-to-Text
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Endpoints
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/audio/transcriptions` — multipart upload, returns text
|
||||
- `POST $OMNIROUTE_URL/v1/audio/translations` — transcribe + translate to English
|
||||
|
||||
## Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/stt | jq '.data[]'
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/audio/transcriptions \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-F "file=@audio.mp3" \
|
||||
-F "model=whisper-1" \
|
||||
-F "response_format=verbose_json"
|
||||
```
|
||||
|
||||
Response: `{ text, language, duration, segments?:[{ start, end, text }] }`
|
||||
|
||||
## Supported formats
|
||||
|
||||
Audio: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`.
|
||||
Response formats: `json`, `text`, `srt`, `verbose_json`, `vtt`.
|
||||
|
||||
## Errors
|
||||
|
||||
- `400 invalid_file_format` → unsupported audio format
|
||||
- `400 file_too_large` → exceeds provider limit (usually 25MB)
|
||||
- `503` → provider unavailable; try another model in `/v1/models/stt`
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: omniroute-tts
|
||||
description: Text-to-speech via OmniRoute using OpenAI /v1/audio/speech format with auto-fallback across OpenAI TTS, ElevenLabs, Azure Neural, Google Cloud TTS. Use when the user wants spoken audio output from text.
|
||||
---
|
||||
|
||||
# OmniRoute — Text-to-Speech
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Endpoint
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/audio/speech` — returns binary audio (mp3/opus/wav/flac)
|
||||
|
||||
## Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/tts | jq '.data[]'
|
||||
```
|
||||
|
||||
Each entry includes `voices:[...]` for the available voice names per provider.
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/audio/speech \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "tts-1",
|
||||
"input": "Hello from OmniRoute.",
|
||||
"voice": "alloy",
|
||||
"response_format": "mp3"
|
||||
}' --output speech.mp3
|
||||
```
|
||||
|
||||
## Voices
|
||||
|
||||
Voice names vary by provider. Check `/v1/models/tts` — each entry has `voices:[...]`.
|
||||
Common OpenAI voices: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`.
|
||||
|
||||
## Errors
|
||||
|
||||
- `400 invalid_voice` → voice not supported by this model
|
||||
- `400 input_too_long` → input exceeds model character limit
|
||||
- `503` → provider unavailable; try another model in `/v1/models/tts`
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
name: omniroute-web-fetch
|
||||
description: Fetch a URL and convert to clean markdown via OmniRoute proxying Jina Reader, Firecrawl, raw HTML strip. Use when the user wants to ingest a webpage as markdown for context in an LLM conversation.
|
||||
---
|
||||
|
||||
# OmniRoute — Web Fetch
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Endpoint
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/web/fetch`
|
||||
|
||||
## Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/web | jq '.data[] | select(.kind == "webFetch")'
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/web/fetch \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "jina/reader",
|
||||
"url": "https://anthropic.com",
|
||||
"format": "markdown"
|
||||
}'
|
||||
```
|
||||
|
||||
Response: `{ url, title, markdown, links?:[...], images?:[...] }`
|
||||
|
||||
## Parameters
|
||||
|
||||
| Field | Type | Description |
|
||||
| -------- | ------ | ----------------------------------------------------------------------- |
|
||||
| `model` | string | Provider from `/v1/models/web` (e.g. `jina/reader`, `firecrawl/scrape`) |
|
||||
| `url` | string | URL to fetch |
|
||||
| `format` | string | `markdown` (default), `html`, `text` |
|
||||
|
||||
## Errors
|
||||
|
||||
- `400 invalid_url` → URL must be http/https
|
||||
- `403 blocked` → provider blocked by target site; try a different model
|
||||
- `503` → provider unavailable; try another model in `/v1/models/web`
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: omniroute-web-search
|
||||
description: Web search via OmniRoute proxying Tavily, Brave Search, SerpAPI, Exa with auto-fallback. Use when the user wants live web search results, current news, or facts that may be beyond the LLM training cutoff.
|
||||
---
|
||||
|
||||
# OmniRoute — Web Search
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Endpoint
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/web/search` — unified search format
|
||||
|
||||
## Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/web | jq '.data[] | select(.kind == "webSearch")'
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/web/search \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "tavily/search",
|
||||
"query": "OmniRoute github latest release",
|
||||
"max_results": 5,
|
||||
"include_answer": true
|
||||
}'
|
||||
```
|
||||
|
||||
Response: `{ answer?, results:[{ url, title, content, score }] }`
|
||||
|
||||
## Parameters
|
||||
|
||||
| Field | Type | Description |
|
||||
| ---------------- | ------- | ------------------------------------ |
|
||||
| `model` | string | Provider model from `/v1/models/web` |
|
||||
| `query` | string | Search query |
|
||||
| `max_results` | number | Max results (default: 5) |
|
||||
| `include_answer` | boolean | Include AI-synthesized answer |
|
||||
| `search_depth` | string | `basic` or `advanced` (Tavily) |
|
||||
|
||||
## Errors
|
||||
|
||||
- `400 query_too_long` → shorten the search query
|
||||
- `503` → provider unavailable; try another model in `/v1/models/web`
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
name: omniroute
|
||||
description: Entry point for OmniRoute — local/remote AI gateway with OpenAI-compatible REST for chat, image, TTS, STT, embeddings, web search, web fetch, MCP, A2A. Use when the user mentions OmniRoute, OMNIROUTE_URL, or wants AI without writing provider boilerplate. This skill covers setup + indexes capability skills; fetch the relevant capability SKILL.md from the URLs below when needed.
|
||||
---
|
||||
|
||||
# OmniRoute
|
||||
|
||||
Local/remote AI gateway exposing OpenAI-compatible REST. One key, 207+ providers,
|
||||
auto-fallback, RTK token saver, MCP server, A2A agents.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
export OMNIROUTE_URL="http://localhost:20128" # or VPS / tunnel URL
|
||||
export OMNIROUTE_KEY="sk-..." # from Dashboard → API Keys
|
||||
```
|
||||
|
||||
All requests: `${OMNIROUTE_URL}/v1/...` with `Authorization: Bearer ${OMNIROUTE_KEY}`.
|
||||
|
||||
Verify: `curl $OMNIROUTE_URL/api/health` → `{"ok":true}`
|
||||
|
||||
## Discover models
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models # chat/LLM (default)
|
||||
curl $OMNIROUTE_URL/v1/models/image # image-gen
|
||||
curl $OMNIROUTE_URL/v1/models/tts # text-to-speech
|
||||
curl $OMNIROUTE_URL/v1/models/embedding # embeddings
|
||||
curl $OMNIROUTE_URL/v1/models/web # web search + fetch
|
||||
curl $OMNIROUTE_URL/v1/models/stt # speech-to-text
|
||||
```
|
||||
|
||||
Use `data[].id` as `model` field in requests. Combos appear with `owned_by:"combo"`.
|
||||
|
||||
## Capability skills
|
||||
|
||||
| Capability | Raw URL |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| Chat / code-gen | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-chat/SKILL.md |
|
||||
| Image generation | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-image/SKILL.md |
|
||||
| Text-to-speech | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-tts/SKILL.md |
|
||||
| Speech-to-text | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-stt/SKILL.md |
|
||||
| Embeddings | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-embeddings/SKILL.md |
|
||||
| Web search | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-web-search/SKILL.md |
|
||||
| Web fetch | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-web-fetch/SKILL.md |
|
||||
| MCP server (37 tools) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-mcp/SKILL.md |
|
||||
| A2A protocol | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-a2a/SKILL.md |
|
||||
| Routing & combos | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-routing/SKILL.md |
|
||||
| Token compression | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-compression/SKILL.md |
|
||||
| Monitoring & health | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-monitoring/SKILL.md |
|
||||
|
||||
## CLI skills (omniroute binary)
|
||||
|
||||
| Capability | Raw URL |
|
||||
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| CLI entry point | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md |
|
||||
| CLI admin & lifecycle | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-admin/SKILL.md |
|
||||
| CLI providers & keys | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-providers/SKILL.md |
|
||||
| CLI cloud agents | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-cloud/SKILL.md |
|
||||
| CLI evals & benchmarks | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-eval/SKILL.md |
|
||||
|
||||
## Errors
|
||||
|
||||
- `401` → set/refresh `OMNIROUTE_KEY` (Dashboard → API Keys)
|
||||
- `400 Invalid model format` → check `model` exists in `/v1/models/<kind>`
|
||||
- `503 Provider circuit open` → upstream provider down; retry after `Retry-After` seconds
|
||||
- `429` → rate limited; honor `Retry-After`
|
||||
|
||||
## Differentiators vs OpenAI direct
|
||||
|
||||
- **Auto-fallback** combos (14 strategies): never stop coding even if a provider rate-limits
|
||||
- **RTK token saver**: tool_result compressed via 47 specialized filters (git-diff, test-jest, terraform-plan, docker-logs…) — 20-40% token reduction
|
||||
- **Caveman mode**: optional terse system prompt injection (LITE/FULL/ULTRA) — 15-25% completion reduction
|
||||
- **MCP + A2A** servers built-in (this is the only AI router that exposes both protocols)
|
||||
- **Memory** with FTS5 + Qdrant for persistent agent context
|
||||
- **Guardrails** for PII masking, prompt injection detection, vision policies
|
||||
117
skills/cli-eval/SKILL.md
Normal file
117
skills/cli-eval/SKILL.md
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
name: cli-eval
|
||||
description: Run and manage OmniRoute eval suites from the CLI — create suites, run benchmarks, watch live results, view scorecards, and compare model performance.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Migrated from skills/omniroute-cli-eval/SKILL.md (preserved curated content) -->
|
||||
|
||||
# OmniRoute — CLI Evals
|
||||
|
||||
Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
|
||||
|
||||
## What are evals?
|
||||
|
||||
Evals are automated test suites that score LLM outputs against expected answers or rubrics. OmniRoute stores suites and run results in its local database.
|
||||
|
||||
## Eval suites
|
||||
|
||||
```bash
|
||||
omniroute eval suites list # List all eval suites
|
||||
omniroute eval suites list --json # JSON output
|
||||
|
||||
omniroute eval suites get <suiteId> # Full suite definition
|
||||
```
|
||||
|
||||
### Create a suite
|
||||
|
||||
```bash
|
||||
omniroute eval suites create \
|
||||
--name "code-quality" \
|
||||
--rubric "exact-match" \
|
||||
--samples-file ./samples.jsonl # JSONL: {input, expected_output}
|
||||
```
|
||||
|
||||
Rubric options: `exact-match`, `contains`, `llm-judge`, `regex`.
|
||||
|
||||
`--samples-file` format (one JSON object per line):
|
||||
|
||||
```jsonl
|
||||
{"input": "What is 2+2?", "expected_output": "4"}
|
||||
{"input": "Translate 'hello' to Spanish", "expected_output": "hola"}
|
||||
```
|
||||
|
||||
## Run an eval
|
||||
|
||||
```bash
|
||||
omniroute eval suites run <suiteId> \
|
||||
--model claude-sonnet-4-6 # Run suite against a specific model
|
||||
|
||||
omniroute eval suites run <suiteId> \
|
||||
--model gpt-4o \
|
||||
--watch # Live TUI progress (EvalWatch)
|
||||
```
|
||||
|
||||
The run is asynchronous. Use `--watch` for a live terminal dashboard or poll manually:
|
||||
|
||||
```bash
|
||||
RUN_ID=$(omniroute eval suites run <suiteId> --model claude-sonnet-4-6 --output json | jq -r '.id')
|
||||
omniroute eval get $RUN_ID
|
||||
```
|
||||
|
||||
## Manage runs
|
||||
|
||||
```bash
|
||||
omniroute eval list # List all eval runs
|
||||
omniroute eval list --json
|
||||
|
||||
omniroute eval get <runId> # Run details (status, model, score)
|
||||
omniroute eval results <runId> # Per-sample results
|
||||
omniroute eval scorecard <runId> # Full scorecard with pass/fail per sample
|
||||
omniroute eval cancel <runId> # Cancel a running eval
|
||||
```
|
||||
|
||||
## Scorecard output
|
||||
|
||||
```bash
|
||||
omniroute eval scorecard <runId> --output json
|
||||
```
|
||||
|
||||
Response fields per sample:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "sample-1",
|
||||
"score": 0.95,
|
||||
"passed": true,
|
||||
"input": "What is 2+2?",
|
||||
"output": "4",
|
||||
"expected": "4"
|
||||
}
|
||||
```
|
||||
|
||||
## Comparing models
|
||||
|
||||
Run the same suite against multiple models and compare:
|
||||
|
||||
```bash
|
||||
for MODEL in claude-sonnet-4-6 gpt-4o gemini-2.0-flash; do
|
||||
omniroute eval suites run $SUITE_ID --model $MODEL --output json | jq '{model: .model, score: .score}'
|
||||
done
|
||||
```
|
||||
|
||||
## CI integration
|
||||
|
||||
```bash
|
||||
# Run and fail CI if score drops below threshold
|
||||
SCORE=$(omniroute eval suites run $SUITE_ID --model claude-sonnet-4-6 --output json | jq -r '.score')
|
||||
python3 -c "import sys; score=float('$SCORE'); sys.exit(0 if score >= 0.90 else 1)"
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `suites create` fails with `invalid rubric` → use one of: `exact-match`, `contains`, `llm-judge`, `regex`
|
||||
- `suites run` returns `model not found` → verify model ID with `omniroute models --search <name>`
|
||||
- `eval get` shows `status: failed` → check `omniroute logs --search eval` for error details
|
||||
- `scorecard` returns empty results → the run may still be `running`; poll `omniroute eval get <runId>` until `status` is `completed`
|
||||
<!-- skill:custom-end -->
|
||||
149
skills/cli-providers/SKILL.md
Normal file
149
skills/cli-providers/SKILL.md
Normal file
@@ -0,0 +1,149 @@
|
||||
---
|
||||
name: cli-providers
|
||||
description: Manage OmniRoute provider connections, API keys, and routing combos via CLI — add/list/test/remove providers, rotate keys, run OAuth flows, list models, and create/switch combos.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Migrated from skills/omniroute-cli-providers/SKILL.md (preserved curated content) -->
|
||||
|
||||
# OmniRoute — CLI Providers & Keys
|
||||
|
||||
Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
|
||||
|
||||
## Provider catalog (available providers)
|
||||
|
||||
```bash
|
||||
omniroute providers available # Full OmniRoute provider catalog
|
||||
omniroute providers available --search openai # Filter by id, name, alias
|
||||
omniroute providers available --category api-key # Filter by category
|
||||
omniroute providers available --json # Machine-readable JSON
|
||||
```
|
||||
|
||||
Categories: `api-key`, `oauth`, `free`, `local`, `combo`.
|
||||
|
||||
## Configured provider connections
|
||||
|
||||
```bash
|
||||
omniroute providers list # Connections in your DB
|
||||
omniroute providers list --json
|
||||
```
|
||||
|
||||
## Testing connections
|
||||
|
||||
```bash
|
||||
omniroute providers test <id|name> # Test one configured connection
|
||||
omniroute providers test-all # Test every active connection (TUI progress)
|
||||
omniroute providers validate # Local-only structural validation (no HTTP)
|
||||
```
|
||||
|
||||
`test-all` opens an interactive TUI that shows live pass/fail per connection. Use `--json` to get a machine-readable result:
|
||||
|
||||
```bash
|
||||
omniroute providers test-all --json
|
||||
```
|
||||
|
||||
## API key management (OmniRoute keys)
|
||||
|
||||
These manage the OmniRoute API keys issued under **API Manager** — not provider credentials.
|
||||
|
||||
```bash
|
||||
omniroute keys list # List all OmniRoute API keys
|
||||
omniroute keys add <provider> [apiKey] # Add an API key for a provider
|
||||
omniroute keys remove <provider> # Remove an API key
|
||||
omniroute keys regenerate <id> # Regenerate (rotate) a key
|
||||
omniroute keys revoke <id> # Revoke a key (disables it)
|
||||
omniroute keys reveal <id> # Show the full key value
|
||||
omniroute keys usage <id> # Show usage stats for a key
|
||||
|
||||
omniroute keys rotate <id> # Rotate + revoke old key atomically
|
||||
omniroute keys expiration list # List key expiration times
|
||||
```
|
||||
|
||||
### Key policies
|
||||
|
||||
```bash
|
||||
omniroute keys policy show <id> # Show rate-limit / permission policy
|
||||
omniroute keys policy set <id> \
|
||||
--rate-limit 100 \
|
||||
--rate-window minute \
|
||||
--permissions chat,models # Set policy on a key
|
||||
```
|
||||
|
||||
## Models
|
||||
|
||||
```bash
|
||||
omniroute models # List all models (all providers)
|
||||
omniroute models openai # Filter by provider
|
||||
omniroute models --search gpt # Search by name
|
||||
omniroute models --json # JSON output
|
||||
```
|
||||
|
||||
## OAuth providers
|
||||
|
||||
```bash
|
||||
omniroute oauth list # List OAuth-configured providers
|
||||
omniroute oauth login <provider> # Start browser-based OAuth flow
|
||||
omniroute oauth logout <provider> # Revoke OAuth token
|
||||
omniroute oauth status <provider> # Show token state + expiry
|
||||
omniroute oauth refresh <provider> # Force token refresh
|
||||
```
|
||||
|
||||
For OAuth providers (Gemini, Windsurf, Antigravity, etc.) the `login` command opens the OmniRoute dashboard OAuth flow in your browser.
|
||||
|
||||
## Provider nodes (multi-account routing)
|
||||
|
||||
Provider nodes let you attach multiple API keys / accounts to one logical provider for round-robin or failover.
|
||||
|
||||
```bash
|
||||
omniroute nodes list <provider> # List nodes for a provider
|
||||
omniroute nodes add <provider> --api-key <key> # Add a node
|
||||
omniroute nodes remove <provider> <nodeId> # Remove a node
|
||||
omniroute nodes test <provider> <nodeId> # Test one node
|
||||
```
|
||||
|
||||
## Routing combos (CLI)
|
||||
|
||||
Create and manage routing combos from the terminal:
|
||||
|
||||
```bash
|
||||
omniroute combo list # List all combos
|
||||
omniroute combo create <name> \
|
||||
--strategy priority \
|
||||
--targets anthropic/claude-opus-4-7,openai/gpt-4o # Create combo
|
||||
omniroute combo switch <name> # Activate a combo as default
|
||||
omniroute combo delete <name> # Delete a combo
|
||||
omniroute combo suggest --task "code review" # Ask OmniRoute to recommend a combo
|
||||
```
|
||||
|
||||
For the full REST API for combos see [omniroute-routing skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-routing/SKILL.md).
|
||||
|
||||
## Quota & usage
|
||||
|
||||
```bash
|
||||
omniroute quota # Provider quota usage + reset times
|
||||
omniroute usage # Request + token usage summary
|
||||
omniroute cost # Cost breakdown (by provider/model)
|
||||
```
|
||||
|
||||
## Compression (CLI)
|
||||
|
||||
```bash
|
||||
omniroute compression status # Current compression mode + savings stats
|
||||
omniroute compression set --mode rtk # Enable RTK compression
|
||||
omniroute compression set --mode stacked # Enable stacked (RTK + Caveman)
|
||||
omniroute compression set --mode off # Disable compression
|
||||
omniroute compression preview --mode rtk --text "..." # Preview savings for sample text
|
||||
```
|
||||
|
||||
## Health
|
||||
|
||||
```bash
|
||||
omniroute health # Detailed health: circuit breakers, cache, memory
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `providers test <id>` fails with 401 → API key stored for that provider is wrong; use `keys remove` + `keys add` to reset it
|
||||
- `oauth login` opens but doesn't complete → the OAuth token endpoint may be firewalled; use API key auth instead
|
||||
- `combo create` fails with `strategy unknown` → use one of: `priority`, `weighted`, `round-robin`, `fill-first`, `least-used`, `cost-optimized`, `auto`, `random`, `strict-random`, `p2c`, `reset-aware`, `lkgp`, `context-optimized`, `context-relay`
|
||||
<!-- skill:custom-end -->
|
||||
245
skills/cli-serve/SKILL.md
Normal file
245
skills/cli-serve/SKILL.md
Normal file
@@ -0,0 +1,245 @@
|
||||
---
|
||||
name: cli-serve
|
||||
description: OmniRoute CLI entry point and server admin — install, global flags, output formats, server lifecycle (start/stop/restart), setup wizard, diagnostics, backup/restore, autostart, tunnels, and CI/Docker provisioning.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Aggregated from: omniroute-cli (setup + index), omniroute-cli-admin (lifecycle/setup/backup/tunnel) -->
|
||||
|
||||
## Setup
|
||||
|
||||
The `omniroute` binary ships with the OmniRoute server. It is both the server launcher and a full management CLI with 250+ commands across 39 groups.
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
npm install -g omniroute # npm registry
|
||||
# or: use the binary bundled with the desktop app
|
||||
```
|
||||
|
||||
Requires Node.js ≥20.20.2, ≥22.22.2, or ≥24.
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
omniroute --version # prints installed version
|
||||
omniroute --help # full command tree
|
||||
```
|
||||
|
||||
### Connection
|
||||
|
||||
Every CLI command that talks to the server reads two values:
|
||||
|
||||
| Source | Variable / Flag |
|
||||
| -------- | ------------------------------------ |
|
||||
| Base URL | `OMNIROUTE_BASE_URL` or `--base-url` |
|
||||
| API key | `OMNIROUTE_API_KEY` or `--api-key` |
|
||||
|
||||
Default base URL: `http://localhost:20128`
|
||||
|
||||
```bash
|
||||
export OMNIROUTE_BASE_URL="http://localhost:20128"
|
||||
export OMNIROUTE_API_KEY="sk-..." # from Dashboard → API Manager
|
||||
```
|
||||
|
||||
For a remote server:
|
||||
|
||||
```bash
|
||||
export OMNIROUTE_BASE_URL="https://your-server.com"
|
||||
```
|
||||
|
||||
### Global flags
|
||||
|
||||
| Flag | Description |
|
||||
| ------------------- | -------------------------------------------------------- |
|
||||
| `--base-url <url>` | Override server URL for this invocation |
|
||||
| `--api-key <key>` | Override API key for this invocation |
|
||||
| `--output <format>` | Output format: `table` (default), `json`, `jsonl`, `csv` |
|
||||
| `--json` | Shorthand for `--output json` |
|
||||
| `--non-interactive` | Disable prompts — for CI / shell scripts |
|
||||
| `--no-open` | Don't auto-open the browser on start |
|
||||
| `--port <n>` | Override default port 20128 |
|
||||
| `--help`, `-h` | Show help for the current command |
|
||||
| `--version`, `-v` | Print the installed version |
|
||||
|
||||
### Output formats
|
||||
|
||||
All listing commands support `--output`:
|
||||
|
||||
```bash
|
||||
omniroute combo list # human-readable table
|
||||
omniroute combo list --output json # JSON array
|
||||
omniroute combo list --output jsonl # one JSON object per line
|
||||
omniroute combo list --output csv # CSV with header row
|
||||
```
|
||||
|
||||
### Quick start: one-shot server + provider setup
|
||||
|
||||
```bash
|
||||
# 1. Start server
|
||||
omniroute
|
||||
|
||||
# 2. (First run) interactive setup wizard
|
||||
omniroute setup
|
||||
|
||||
# 3. Verify everything is healthy
|
||||
omniroute doctor
|
||||
```
|
||||
|
||||
### CLI capability skills
|
||||
|
||||
| Capability | Skill |
|
||||
| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
|
||||
| Server admin + backup | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-admin/SKILL.md |
|
||||
| Provider & key management | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-providers/SKILL.md |
|
||||
| Cloud agents (Codex / Devin / Jules) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-cloud/SKILL.md |
|
||||
| Evals & benchmarking | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-eval/SKILL.md |
|
||||
|
||||
### Errors
|
||||
|
||||
- `Connection refused` → server not running; run `omniroute` or `omniroute serve`
|
||||
- `401 Unauthorized` → wrong or missing API key
|
||||
- `command not found: omniroute` → not in PATH; check `npm root -g` or re-install
|
||||
- `doctor` reports SQLite incompatible → `npm rebuild better-sqlite3` in the app directory
|
||||
|
||||
## Admin lifecycle
|
||||
|
||||
Requires the `omniroute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) for install + global flags.
|
||||
|
||||
### Server lifecycle
|
||||
|
||||
```bash
|
||||
omniroute # Start server (default port 20128)
|
||||
omniroute serve # Explicit alias
|
||||
omniroute --port 3000 # Override port
|
||||
omniroute --no-open # Don't auto-open browser
|
||||
omniroute --mcp # Start as MCP server (stdio transport)
|
||||
|
||||
omniroute stop # Stop the running server
|
||||
omniroute restart # Restart the server
|
||||
|
||||
omniroute dashboard # Open dashboard in browser
|
||||
omniroute open # Alias for dashboard
|
||||
omniroute status # Runtime status (uptime, requests, providers)
|
||||
```
|
||||
|
||||
### Setup & provisioning
|
||||
|
||||
#### Interactive wizard
|
||||
|
||||
```bash
|
||||
omniroute setup # Step-by-step interactive setup
|
||||
```
|
||||
|
||||
#### Non-interactive (CI / Docker)
|
||||
|
||||
```bash
|
||||
omniroute setup --non-interactive \
|
||||
--password 'admin-password' \
|
||||
--add-provider \
|
||||
--provider openai \
|
||||
--api-key 'sk-...' \
|
||||
--test-provider
|
||||
```
|
||||
|
||||
Environment variables for non-interactive setup:
|
||||
|
||||
| Variable | Purpose |
|
||||
| ----------------------------- | -------------------------------------------- |
|
||||
| `OMNIROUTE_SETUP_PASSWORD` | Admin password (≥8 chars) |
|
||||
| `OMNIROUTE_PROVIDER` | Provider id (e.g. `openai`, `anthropic`) |
|
||||
| `OMNIROUTE_PROVIDER_NAME` | Display name for the connection |
|
||||
| `OMNIROUTE_PROVIDER_BASE_URL` | Optional OpenAI-compatible base URL override |
|
||||
| `OMNIROUTE_API_KEY` | Provider API key |
|
||||
| `OMNIROUTE_DEFAULT_MODEL` | Optional default model |
|
||||
| `DATA_DIR` | Override OmniRoute data directory |
|
||||
|
||||
### Diagnostics
|
||||
|
||||
```bash
|
||||
omniroute doctor # Full health check
|
||||
omniroute doctor --json # Machine-readable JSON
|
||||
omniroute doctor --no-liveness # Skip HTTP health probe
|
||||
omniroute doctor --host 0.0.0.0 # Override liveness host
|
||||
omniroute doctor --liveness-url <url> # Full URL override
|
||||
```
|
||||
|
||||
Checks performed: Config, Database, Storage/encryption, Port, Node runtime, Native binary (better-sqlite3), Memory, Server liveness.
|
||||
|
||||
Exit code is non-zero if any check fails — useful in CI:
|
||||
|
||||
```bash
|
||||
omniroute doctor --json | jq '.checks[] | select(.status=="fail")'
|
||||
```
|
||||
|
||||
### Backup & restore
|
||||
|
||||
```bash
|
||||
omniroute backup # Snapshot config + SQLite DB to ~/.omniroute/backups/
|
||||
omniroute restore # Restore from a previous snapshot (interactive picker)
|
||||
```
|
||||
|
||||
### Autostart (system tray / startup)
|
||||
|
||||
```bash
|
||||
omniroute autostart enable # Register OmniRoute as a system startup item
|
||||
omniroute autostart disable # Remove startup registration
|
||||
omniroute autostart status # Show current autostart state
|
||||
```
|
||||
|
||||
On Linux: creates a **systemd user service** (`~/.config/systemd/user/omniroute.service`) and enables **linger** so the service can start after reboot without a graphical login; on desktop sessions it also adds an XDG autostart entry with `--tray`. On macOS: LaunchAgent plist. On Windows: registry startup entry.
|
||||
|
||||
### Tunnels (public URL)
|
||||
|
||||
Expose a local OmniRoute instance via a secure tunnel:
|
||||
|
||||
```bash
|
||||
omniroute tunnel list # List active tunnels
|
||||
omniroute tunnel create cloudflare # Start a Cloudflare Tunnel (free)
|
||||
omniroute tunnel create tailscale # Start a Tailscale funnel
|
||||
omniroute tunnel create ngrok # Start an ngrok tunnel
|
||||
omniroute tunnel stop <id> # Stop a running tunnel
|
||||
```
|
||||
|
||||
The tunnel URL is printed and can be used as `OMNIROUTE_BASE_URL` from remote machines.
|
||||
|
||||
### Config & environment
|
||||
|
||||
```bash
|
||||
omniroute config show # Display current effective configuration
|
||||
omniroute env show # List all OmniRoute environment variables
|
||||
omniroute env get <KEY> # Get a single env var value
|
||||
omniroute env set <KEY> <value> # Set an env var (temporary — until restart)
|
||||
```
|
||||
|
||||
### Recovery
|
||||
|
||||
```bash
|
||||
omniroute reset-password # Reset the admin password interactively
|
||||
omniroute reset-encrypted-columns # Dry-run: show encrypted credential columns
|
||||
omniroute reset-encrypted-columns --force # Null out encrypted credentials in SQLite
|
||||
```
|
||||
|
||||
Use `reset-encrypted-columns --force` only if `STORAGE_ENCRYPTION_KEY` was lost and you need to re-enter all provider API keys.
|
||||
|
||||
### Logs
|
||||
|
||||
```bash
|
||||
omniroute logs # Stream live request logs
|
||||
omniroute logs --json # JSON log entries
|
||||
omniroute logs --search <term> # Filter by term
|
||||
omniroute logs --follow # Tail mode (keep streaming)
|
||||
```
|
||||
|
||||
### Update
|
||||
|
||||
```bash
|
||||
omniroute update # Check for a newer version and prompt to update
|
||||
```
|
||||
|
||||
### Errors
|
||||
|
||||
- `doctor` shows `STORAGE_ENCRYPTION_KEY missing` → set the key in `.env` or run `reset-encrypted-columns --force` to wipe and re-enter credentials
|
||||
- `doctor` reports native binary fail → `npm rebuild better-sqlite3` in the OmniRoute app directory
|
||||
- `tunnel create cloudflare` hangs → ensure `cloudflared` is installed: `brew install cloudflare/cloudflare/cloudflared`
|
||||
<!-- skill:custom-end -->
|
||||
75
skills/omni-agents-a2a/SKILL.md
Normal file
75
skills/omni-agents-a2a/SKILL.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: omni-agents-a2a
|
||||
description: OmniRoute exposes an A2A (Agent-to-Agent) JSON-RPC 2.0 server with 5 skills (smart-routing, quota-management, provider-discovery, cost-analysis, health-report). Use when the user wants OmniRoute to act as an agent peer in an A2A network or multi-agent pipeline.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Migrated from skills/omniroute-a2a/SKILL.md (preserved curated content) -->
|
||||
|
||||
# OmniRoute — A2A Protocol
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
OmniRoute publishes an Agent Card at `/.well-known/agent.json` and accepts
|
||||
JSON-RPC 2.0 calls at `/a2a`.
|
||||
|
||||
## Discovery
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/.well-known/agent.json
|
||||
```
|
||||
|
||||
Returns Agent Card with skills, endpoints, auth scheme.
|
||||
|
||||
## Available skills
|
||||
|
||||
| Skill | Purpose |
|
||||
| -------------------- | ----------------------------------------------------------------------------------- |
|
||||
| `smart-routing` | Given a prompt, recommends best provider/model combo |
|
||||
| `quota-management` | Reports quota balance for given provider/account |
|
||||
| `provider-discovery` | Lists providers matching capability filters (vision, JSON mode, tools, max-context) |
|
||||
| `cost-analysis` | Estimates cost for a given request shape |
|
||||
| `health-report` | Returns system health (circuit states, latencies, errors) |
|
||||
|
||||
## Call example (JSON-RPC 2.0)
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/a2a \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "tasks/send",
|
||||
"params": {
|
||||
"skillId": "smart-routing",
|
||||
"input": { "prompt_length": 4000, "tools": true, "vision": false }
|
||||
},
|
||||
"id": 1
|
||||
}'
|
||||
```
|
||||
|
||||
## Response shape
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"result": {
|
||||
"taskId": "...",
|
||||
"status": "completed",
|
||||
"output": { "recommended_combo": "...", "reasoning": "..." }
|
||||
},
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `-32600` → invalid request (bad JSON-RPC envelope)
|
||||
- `-32601` → method not found (check `method` field)
|
||||
- `-32602` → invalid params (check `skillId` against Agent Card)
|
||||
- `401` → missing/invalid `OMNIROUTE_KEY`
|
||||
|
||||
## Reference
|
||||
|
||||
Full docs: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/A2A-SERVER.md
|
||||
<!-- skill:custom-end -->
|
||||
80
skills/omni-auth/SKILL.md
Normal file
80
skills/omni-auth/SKILL.md
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
name: omni-auth
|
||||
description: Entry point for OmniRoute — local/remote AI gateway with OpenAI-compatible REST for chat, image, TTS, STT, embeddings, web search, web fetch, MCP, A2A. Setup, index of capability skills, and differentiators.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Migrated from skills/omniroute/SKILL.md (preserved curated content) -->
|
||||
|
||||
# OmniRoute
|
||||
|
||||
Local/remote AI gateway exposing OpenAI-compatible REST. One key, 207+ providers,
|
||||
auto-fallback, RTK token saver, MCP server, A2A agents.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
export OMNIROUTE_URL="http://localhost:20128" # or VPS / tunnel URL
|
||||
export OMNIROUTE_KEY="sk-..." # from Dashboard → API Keys
|
||||
```
|
||||
|
||||
All requests: `${OMNIROUTE_URL}/v1/...` with `Authorization: Bearer ${OMNIROUTE_KEY}`.
|
||||
|
||||
Verify: `curl $OMNIROUTE_URL/api/health` → `{"ok":true}`
|
||||
|
||||
## Discover models
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models # chat/LLM (default)
|
||||
curl $OMNIROUTE_URL/v1/models/image # image-gen
|
||||
curl $OMNIROUTE_URL/v1/models/tts # text-to-speech
|
||||
curl $OMNIROUTE_URL/v1/models/embedding # embeddings
|
||||
curl $OMNIROUTE_URL/v1/models/web # web search + fetch
|
||||
curl $OMNIROUTE_URL/v1/models/stt # speech-to-text
|
||||
```
|
||||
|
||||
Use `data[].id` as `model` field in requests. Combos appear with `owned_by:"combo"`.
|
||||
|
||||
## Capability skills
|
||||
|
||||
| Capability | Raw URL |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| Chat / code-gen | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-chat/SKILL.md |
|
||||
| Image generation | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-image/SKILL.md |
|
||||
| Text-to-speech | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-tts/SKILL.md |
|
||||
| Speech-to-text | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-stt/SKILL.md |
|
||||
| Embeddings | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-embeddings/SKILL.md |
|
||||
| Web search | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-web-search/SKILL.md |
|
||||
| Web fetch | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-web-fetch/SKILL.md |
|
||||
| MCP server (37 tools) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-mcp/SKILL.md |
|
||||
| A2A protocol | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-a2a/SKILL.md |
|
||||
| Routing & combos | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-routing/SKILL.md |
|
||||
| Token compression | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-compression/SKILL.md |
|
||||
| Monitoring & health | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-monitoring/SKILL.md |
|
||||
|
||||
## CLI skills (omniroute binary)
|
||||
|
||||
| Capability | Raw URL |
|
||||
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| CLI entry point | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md |
|
||||
| CLI admin & lifecycle | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-admin/SKILL.md |
|
||||
| CLI providers & keys | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-providers/SKILL.md |
|
||||
| CLI cloud agents | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-cloud/SKILL.md |
|
||||
| CLI evals & benchmarks | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-eval/SKILL.md |
|
||||
|
||||
## Errors
|
||||
|
||||
- `401` → set/refresh `OMNIROUTE_KEY` (Dashboard → API Keys)
|
||||
- `400 Invalid model format` → check `model` exists in `/v1/models/<kind>`
|
||||
- `503 Provider circuit open` → upstream provider down; retry after `Retry-After` seconds
|
||||
- `429` → rate limited; honor `Retry-After`
|
||||
|
||||
## Differentiators vs OpenAI direct
|
||||
|
||||
- **Auto-fallback** combos (14 strategies): never stop coding even if a provider rate-limits
|
||||
- **RTK token saver**: tool_result compressed via 47 specialized filters (git-diff, test-jest, terraform-plan, docker-logs…) — 20-40% token reduction
|
||||
- **Caveman mode**: optional terse system prompt injection (LITE/FULL/ULTRA) — 15-25% completion reduction
|
||||
- **MCP + A2A** servers built-in (this is the only AI router that exposes both protocols)
|
||||
- **Memory** with FTS5 + Qdrant for persistent agent context
|
||||
- **Guardrails** for PII masking, prompt injection detection, vision policies
|
||||
<!-- skill:custom-end -->
|
||||
133
skills/omni-combos-routing/SKILL.md
Normal file
133
skills/omni-combos-routing/SKILL.md
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
name: omni-combos-routing
|
||||
description: Create and configure OmniRoute routing combos, choose from 14 strategies (priority, weighted, auto, round-robin, cost-optimized, etc.), activate Auto-combo 9-factor scoring, and set up fallback chains.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Migrated from skills/omniroute-routing/SKILL.md (preserved curated content) -->
|
||||
|
||||
# OmniRoute — Routing & Combos
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## What is a combo?
|
||||
|
||||
A combo is a named group of providers/models with a routing strategy. All requests through a combo are automatically distributed, failed-over, and load-balanced — the caller uses a single model ID like `my-combo`.
|
||||
|
||||
## List existing combos
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/combos \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Response includes `id`, `name`, `strategy`, `enabled`, and per-target stats.
|
||||
|
||||
## Create a combo
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/combos \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "my-combo",
|
||||
"strategy": "priority",
|
||||
"targets": [
|
||||
{ "provider": "anthropic", "model": "claude-opus-4-7", "weight": 1 },
|
||||
{ "provider": "openai", "model": "gpt-4o", "weight": 1 }
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## 14 routing strategies
|
||||
|
||||
| Strategy | Description |
|
||||
| ------------------- | -------------------------------------------------- |
|
||||
| `priority` | Always use target[0]; fall back on error |
|
||||
| `weighted` | Distribute by weight percentage |
|
||||
| `round-robin` | Rotate targets in order |
|
||||
| `fill-first` | Fill quota of target[0] before spilling |
|
||||
| `least-used` | Route to target with fewest active requests |
|
||||
| `cost-optimized` | Pick cheapest target for the token estimate |
|
||||
| `auto` | 9-factor scoring: cost + latency + quota + circuit |
|
||||
| `random` | Uniform random selection |
|
||||
| `strict-random` | Random without repeating until all used |
|
||||
| `p2c` | Power-of-2-choices: sample 2, pick better |
|
||||
| `reset-aware` | Prefer targets near quota reset time |
|
||||
| `lkgp` | Last-known-good-provider sticky routing |
|
||||
| `context-optimized` | Pick best model for context length |
|
||||
| `context-relay` | Chain models for very long contexts |
|
||||
|
||||
## Auto-combo (recommended for production)
|
||||
|
||||
Auto-combo scores each candidate on 9 factors every request:
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/combos \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "prod-auto",
|
||||
"strategy": "auto",
|
||||
"targets": [
|
||||
{ "provider": "anthropic", "model": "claude-sonnet-4-6" },
|
||||
{ "provider": "openai", "model": "gpt-4o-mini" },
|
||||
{ "provider": "google", "model": "gemini-2.0-flash" }
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Then call it with:
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/chat/completions \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "model": "prod-auto", "messages": [{ "role": "user", "content": "Hello" }] }'
|
||||
```
|
||||
|
||||
## Activate / deactivate a combo
|
||||
|
||||
```bash
|
||||
# Activate
|
||||
curl -X PUT $OMNIROUTE_URL/api/combos/{id}/toggle \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-d '{ "enabled": true }'
|
||||
```
|
||||
|
||||
## Get combo metrics
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/combos/{id}/metrics \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Returns p50/p95/p99 latency, success rate, cost, and per-target breakdown.
|
||||
|
||||
## Simulate routing (dry run)
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/routing/simulate \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "comboId": "{id}", "messages": [{ "role": "user", "content": "test" }] }'
|
||||
```
|
||||
|
||||
Returns which provider would be selected and why — no actual API call is made.
|
||||
|
||||
## Via MCP (if OmniRoute is your MCP server)
|
||||
|
||||
```
|
||||
omniroute_list_combos → list all combos
|
||||
omniroute_switch_combo → enable/disable a combo
|
||||
omniroute_set_routing_strategy → change strategy at runtime
|
||||
omniroute_simulate_route → dry-run routing decision
|
||||
omniroute_best_combo_for_task → get recommendation by task type
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `404 combo not found` → check `id` from `/api/combos`
|
||||
- `400 invalid strategy` → use one of the 14 strategies above
|
||||
- `409 name conflict` → combo name already exists
|
||||
<!-- skill:custom-end -->
|
||||
135
skills/omni-compression/SKILL.md
Normal file
135
skills/omni-compression/SKILL.md
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
name: omni-compression
|
||||
description: Configure OmniRoute token compression to save 60-90% of context tokens. Covers RTK (command/tool output), Caveman (prose), stacked mode (both), and the MCP accessibility-tree filter (browser snapshots).
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Migrated from skills/omniroute-compression/SKILL.md (preserved curated content) -->
|
||||
|
||||
# OmniRoute — Compression
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Overview
|
||||
|
||||
OmniRoute compresses token payloads before forwarding to providers. No code changes required — set it once, it applies to all requests transparently.
|
||||
|
||||
| Engine | Best for | Typical savings |
|
||||
| ------------------------- | ------------------------------------ | --------------- |
|
||||
| RTK | Terminal / build / test / git output | 60–90% |
|
||||
| Caveman | Human prose, chat history | 46% input |
|
||||
| Stacked (`rtk → caveman`) | Mixed coding sessions | 78–95% |
|
||||
| MCP accessibility filter | Browser/accessibility tool results | 60–80% |
|
||||
|
||||
## Get current settings
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
## Enable RTK (best for coding agents)
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "mode": "rtk", "enabled": true }'
|
||||
```
|
||||
|
||||
## Enable stacked mode (maximum savings)
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mode": "stacked",
|
||||
"enabled": true,
|
||||
"stackedPipeline": ["rtk", "caveman"]
|
||||
}'
|
||||
```
|
||||
|
||||
## Enable Caveman (prose / chat)
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "mode": "standard", "enabled": true }'
|
||||
```
|
||||
|
||||
Caveman intensities: `lite` (safe), `standard` (balanced), `aggressive` (long sessions), `ultra` (context recovery).
|
||||
|
||||
## Preview compression before enabling
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/compression/preview \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mode": "rtk",
|
||||
"text": "$ npm test\n> jest\n\nPASS src/a.test.ts (2.1s)\nPASS src/b.test.ts (1.8s)\n..."
|
||||
}'
|
||||
```
|
||||
|
||||
Response includes `compressed`, `original_length`, `compressed_length`, `savings_pct`.
|
||||
|
||||
## MCP accessibility-tree filter (browser agent use)
|
||||
|
||||
When OmniRoute is used with browser/Playwright MCP tools, it automatically compresses verbose accessibility-tree tool results. Enabled by default; configure thresholds:
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mcpAccessibility": {
|
||||
"enabled": true,
|
||||
"collapseThreshold": 30,
|
||||
"maxTextChars": 50000
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
`collapseThreshold`: collapse sibling lines when ≥ N repeats (default 30).
|
||||
`maxTextChars`: hard truncate after N chars with navigation hint (default 50000).
|
||||
|
||||
## Language packs (Caveman)
|
||||
|
||||
Caveman supports language-aware rules for pt-BR, es, de, fr, ja:
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"mode": "standard",
|
||||
"cavemanConfig": {
|
||||
"language": "pt-BR",
|
||||
"autoDetectLanguage": true
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Via MCP
|
||||
|
||||
```
|
||||
omniroute_compression_status → current settings + savings analytics
|
||||
omniroute_compression_configure → update mode/threshold/language
|
||||
omniroute_set_compression_engine → switch engine at runtime
|
||||
```
|
||||
|
||||
## Disable compression
|
||||
|
||||
```bash
|
||||
curl -X PUT $OMNIROUTE_URL/api/settings/compression \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-d '{ "enabled": false }'
|
||||
```
|
||||
|
||||
## Errors
|
||||
|
||||
- `400 invalid mode` → use `off`, `lite`, `standard`, `aggressive`, `ultra`, `rtk`, or `stacked`
|
||||
- `400 invalid stackedPipeline` → array must contain valid engine ids (`rtk`, `caveman`)
|
||||
<!-- skill:custom-end -->
|
||||
321
skills/omni-inference/SKILL.md
Normal file
321
skills/omni-inference/SKILL.md
Normal file
@@ -0,0 +1,321 @@
|
||||
---
|
||||
name: omni-inference
|
||||
description: Inference capabilities via OmniRoute — chat completions, image generation, text-to-speech, speech-to-text, embeddings, web search, and web fetch. OpenAI-compatible endpoints with auto-fallback across 207+ providers.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Aggregated from: omniroute-chat, omniroute-image, omniroute-tts, omniroute-stt, omniroute-embeddings, omniroute-web-search, omniroute-web-fetch -->
|
||||
|
||||
## Chat completions
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
### Endpoints
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/chat/completions` — OpenAI format
|
||||
- `POST $OMNIROUTE_URL/v1/messages` — Anthropic Messages format
|
||||
- `POST $OMNIROUTE_URL/v1/responses` — OpenAI Responses API
|
||||
|
||||
### Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models | jq '.data[].id'
|
||||
```
|
||||
|
||||
Combos (e.g. `auto`, `cost-optimized`, `subscription`) auto-fallback through multiple providers.
|
||||
|
||||
### OpenAI format example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/chat/completions \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"messages": [{"role": "user", "content": "Refactor this function"}],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
### Anthropic format example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/messages \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-opus-4-7",
|
||||
"max_tokens": 4096,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}'
|
||||
```
|
||||
|
||||
### Tool use
|
||||
|
||||
Supports OpenAI `tools` array and Anthropic `tools` block. Tool results
|
||||
auto-compressed via RTK (47 filters: git-diff, grep, test-jest, terraform-plan,
|
||||
docker-logs, etc.) — 20-40% token savings. Disable per-request with
|
||||
`X-Omniroute-Rtk: off` header.
|
||||
|
||||
### Reasoning / thinking
|
||||
|
||||
Anthropic extended thinking and OpenAI Responses reasoning blocks are forwarded
|
||||
verbatim. Cached automatically via reasoning cache.
|
||||
|
||||
### Errors
|
||||
|
||||
- `401` → invalid API key
|
||||
- `400 invalid_model` → model not in registry; check `/v1/models`
|
||||
- `503 circuit_open` → provider circuit breaker tripped; retry later or use combo
|
||||
- `429 rate_limited` → honor `Retry-After`; consider using a combo for auto-fallback
|
||||
|
||||
## Image generation
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
### Endpoints
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/images/generations` — Text-to-image
|
||||
- `POST $OMNIROUTE_URL/v1/images/edits` — Image edit (mask)
|
||||
- `POST $OMNIROUTE_URL/v1/images/variations` — Variations
|
||||
|
||||
### Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/image | jq '.data[]'
|
||||
```
|
||||
|
||||
Returns `{ id, owned_by, sizes:[...], capabilities:[...] }` per model.
|
||||
|
||||
### Generate example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/images/generations \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "dall-e-3",
|
||||
"prompt": "a red bicycle on a wet street, photoreal",
|
||||
"n": 1,
|
||||
"size": "1024x1024",
|
||||
"response_format": "b64_json"
|
||||
}'
|
||||
```
|
||||
|
||||
Response: `{ created, data: [{ url? or b64_json, revised_prompt }] }`
|
||||
|
||||
### Errors
|
||||
|
||||
- `400 invalid_size` → not supported by this model; check `/v1/models/image`
|
||||
- `400 content_policy_violation` → blocked by provider safety
|
||||
- `503` → provider unavailable; try another model in `/v1/models/image`
|
||||
|
||||
## Text-to-speech
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
### Endpoint
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/audio/speech` — returns binary audio (mp3/opus/wav/flac)
|
||||
|
||||
### Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/tts | jq '.data[]'
|
||||
```
|
||||
|
||||
Each entry includes `voices:[...]` for the available voice names per provider.
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/audio/speech \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "tts-1",
|
||||
"input": "Hello from OmniRoute.",
|
||||
"voice": "alloy",
|
||||
"response_format": "mp3"
|
||||
}' --output speech.mp3
|
||||
```
|
||||
|
||||
### Voices
|
||||
|
||||
Voice names vary by provider. Check `/v1/models/tts` — each entry has `voices:[...]`.
|
||||
Common OpenAI voices: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`.
|
||||
|
||||
### Errors
|
||||
|
||||
- `400 invalid_voice` → voice not supported by this model
|
||||
- `400 input_too_long` → input exceeds model character limit
|
||||
- `503` → provider unavailable; try another model in `/v1/models/tts`
|
||||
|
||||
## Speech-to-text
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
### Endpoints
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/audio/transcriptions` — multipart upload, returns text
|
||||
- `POST $OMNIROUTE_URL/v1/audio/translations` — transcribe + translate to English
|
||||
|
||||
### Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/stt | jq '.data[]'
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/audio/transcriptions \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-F "file=@audio.mp3" \
|
||||
-F "model=whisper-1" \
|
||||
-F "response_format=verbose_json"
|
||||
```
|
||||
|
||||
Response: `{ text, language, duration, segments?:[{ start, end, text }] }`
|
||||
|
||||
### Supported formats
|
||||
|
||||
Audio: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`.
|
||||
Response formats: `json`, `text`, `srt`, `verbose_json`, `vtt`.
|
||||
|
||||
### Errors
|
||||
|
||||
- `400 invalid_file_format` → unsupported audio format
|
||||
- `400 file_too_large` → exceeds provider limit (usually 25MB)
|
||||
- `503` → provider unavailable; try another model in `/v1/models/stt`
|
||||
|
||||
## Embeddings
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
### Endpoint
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/embeddings`
|
||||
|
||||
### Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/embedding | jq '.data[]'
|
||||
```
|
||||
|
||||
Each entry: `{ id, owned_by, dimensions, max_input_tokens }`.
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/embeddings \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "text-embedding-3-large",
|
||||
"input": ["first text", "second text"],
|
||||
"encoding_format": "float"
|
||||
}'
|
||||
```
|
||||
|
||||
Response: `{ data:[{ embedding:[...], index }], usage:{ prompt_tokens, total_tokens } }`
|
||||
|
||||
### Batch input
|
||||
|
||||
`input` accepts a string or array of strings (up to provider batch limit, typically 2048 items).
|
||||
|
||||
### Errors
|
||||
|
||||
- `400 input_too_long` → input exceeds `max_input_tokens` for this model
|
||||
- `400 invalid_encoding_format` → use `float` or `base64`
|
||||
- `503` → provider unavailable; try another model in `/v1/models/embedding`
|
||||
|
||||
## Web search
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
### Endpoint
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/web/search` — unified search format
|
||||
|
||||
### Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/web | jq '.data[] | select(.kind == "webSearch")'
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/web/search \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "tavily/search",
|
||||
"query": "OmniRoute github latest release",
|
||||
"max_results": 5,
|
||||
"include_answer": true
|
||||
}'
|
||||
```
|
||||
|
||||
Response: `{ answer?, results:[{ url, title, content, score }] }`
|
||||
|
||||
### Parameters
|
||||
|
||||
| Field | Type | Description |
|
||||
| ---------------- | ------- | ------------------------------------ |
|
||||
| `model` | string | Provider model from `/v1/models/web` |
|
||||
| `query` | string | Search query |
|
||||
| `max_results` | number | Max results (default: 5) |
|
||||
| `include_answer` | boolean | Include AI-synthesized answer |
|
||||
| `search_depth` | string | `basic` or `advanced` (Tavily) |
|
||||
|
||||
### Errors
|
||||
|
||||
- `400 query_too_long` → shorten the search query
|
||||
- `503` → provider unavailable; try another model in `/v1/models/web`
|
||||
|
||||
## Web fetch
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
### Endpoint
|
||||
|
||||
- `POST $OMNIROUTE_URL/v1/web/fetch`
|
||||
|
||||
### Discover
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/v1/models/web | jq '.data[] | select(.kind == "webFetch")'
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/v1/web/fetch \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "jina/reader",
|
||||
"url": "https://anthropic.com",
|
||||
"format": "markdown"
|
||||
}'
|
||||
```
|
||||
|
||||
Response: `{ url, title, markdown, links?:[...], images?:[...] }`
|
||||
|
||||
### Parameters
|
||||
|
||||
| Field | Type | Description |
|
||||
| -------- | ------ | ----------------------------------------------------------------------- |
|
||||
| `model` | string | Provider from `/v1/models/web` (e.g. `jina/reader`, `firecrawl/scrape`) |
|
||||
| `url` | string | URL to fetch |
|
||||
| `format` | string | `markdown` (default), `html`, `text` |
|
||||
|
||||
### Errors
|
||||
|
||||
- `400 invalid_url` → URL must be http/https
|
||||
- `403 blocked` → provider blocked by target site; try a different model
|
||||
- `503` → provider unavailable; try another model in `/v1/models/web`
|
||||
<!-- skill:custom-end -->
|
||||
75
skills/omni-mcp/SKILL.md
Normal file
75
skills/omni-mcp/SKILL.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: omni-mcp
|
||||
description: OmniRoute exposes a built-in MCP (Model Context Protocol) server with 37 tools (chat, embeddings, memory CRUD, skills, providers, routing, audit) over SSE/stdio/HTTP transports. Use when the user wants to add OmniRoute as an MCP server in Claude Desktop, Cursor, Cline, or any MCP-compatible client.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Migrated from skills/omniroute-mcp/SKILL.md (preserved curated content) -->
|
||||
|
||||
# OmniRoute — MCP Server
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## Transports
|
||||
|
||||
- **stdio** — local IPC, for Claude Desktop / VS Code extensions
|
||||
- **SSE** — `GET $OMNIROUTE_URL/api/mcp/sse`
|
||||
- **Streamable HTTP** — `POST $OMNIROUTE_URL/api/mcp/stream`
|
||||
|
||||
## Claude Desktop config
|
||||
|
||||
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"omniroute": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "omniroute", "--mcp"],
|
||||
"env": { "OMNIROUTE_KEY": "sk-..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Cursor / VS Code config
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"omniroute": {
|
||||
"url": "http://localhost:20128/api/mcp/sse",
|
||||
"headers": { "Authorization": "Bearer sk-..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Available tools (37 total)
|
||||
|
||||
| Scope | Tools |
|
||||
| --------- | -------------------------------------------------------------------------------------------------- |
|
||||
| health | `omniroute_get_health` |
|
||||
| combos | `omniroute_list_combos`, `omniroute_get_combo_metrics`, `omniroute_switch_combo` |
|
||||
| routing | `omniroute_simulate_route`, `omniroute_best_combo_for_task`, `omniroute_explain_route` |
|
||||
| providers | `omniroute_get_provider_metrics`, `omniroute_check_quota`, `omniroute_route_request` |
|
||||
| budget | `omniroute_set_budget_guard`, `omniroute_set_routing_strategy`, `omniroute_set_resilience_profile` |
|
||||
| testing | `omniroute_test_combo` |
|
||||
| memory | `memory_add`, `memory_search`, `memory_delete` |
|
||||
| skills | `skill_invoke`, `skill_list`, `skill_describe`, `skill_register` |
|
||||
| cache | `omniroute_cache_stats`, `omniroute_cache_flush` |
|
||||
| admin | `omniroute_db_health_check`, `omniroute_sync_pricing`, `omniroute_get_session_snapshot` |
|
||||
|
||||
Full list: `GET $OMNIROUTE_URL/api/mcp/tools`
|
||||
|
||||
## Scopes
|
||||
|
||||
Tools are grouped into 13 scopes (chat-only, memory-readonly, full-admin, etc.).
|
||||
Pass scope name as `--scope` arg or via `X-Omniroute-Scope` header.
|
||||
|
||||
## Reference
|
||||
|
||||
Full docs: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/MCP-SERVER.md
|
||||
<!-- skill:custom-end -->
|
||||
118
skills/omni-resilience/SKILL.md
Normal file
118
skills/omni-resilience/SKILL.md
Normal file
@@ -0,0 +1,118 @@
|
||||
---
|
||||
name: omni-resilience
|
||||
description: Monitor OmniRoute system health, provider circuit breakers, per-provider latency (p50/p95/p99), quota usage, and set budget guards. Use when the user wants to check if the system is healthy, debug slow providers, manage spend limits, or set up monitoring.
|
||||
---
|
||||
|
||||
<!-- skill:custom-start -->
|
||||
<!-- Migrated from skills/omniroute-monitoring/SKILL.md (preserved curated content) -->
|
||||
|
||||
# OmniRoute — Monitoring & Health
|
||||
|
||||
Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) for setup.
|
||||
|
||||
## System health
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/health \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Returns: uptime, memory, active connections, circuit breaker states, rate limit status, cache stats.
|
||||
|
||||
Unauthenticated quick check:
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/health
|
||||
# → {"ok":true}
|
||||
```
|
||||
|
||||
## Provider circuit breakers
|
||||
|
||||
Circuit breakers prevent traffic from hitting failing providers.
|
||||
|
||||
States: `CLOSED` (normal), `OPEN` (blocked), `HALF_OPEN` (probe mode — auto-recovers).
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/monitoring/health \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Response includes `circuitBreakers` array with per-provider state and `resetAt` timestamp.
|
||||
|
||||
## Per-provider metrics (p50/p95/p99)
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/providers/metrics \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Response shape per provider:
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "anthropic",
|
||||
"requests": 1247,
|
||||
"successRate": 0.994,
|
||||
"latency": { "p50": 820, "p95": 2100, "p99": 3800 },
|
||||
"circuitState": "CLOSED",
|
||||
"tokensUsed": 2847000
|
||||
}
|
||||
```
|
||||
|
||||
## Via MCP (if OmniRoute is your MCP server)
|
||||
|
||||
```
|
||||
omniroute_get_health → full system health snapshot
|
||||
omniroute_get_provider_metrics → p50/p95/p99 + circuit state per provider
|
||||
omniroute_get_session_snapshot → cost, tokens, errors for current session
|
||||
omniroute_check_quota → quota balance + percent remaining + reset time
|
||||
omniroute_db_health_check → diagnose + auto-repair database drift
|
||||
```
|
||||
|
||||
## Quota check
|
||||
|
||||
```bash
|
||||
curl $OMNIROUTE_URL/api/quota \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Returns used/total tokens and requests per provider/account, with `resetAt` timestamps.
|
||||
|
||||
## Budget guard (spend limit)
|
||||
|
||||
Set a session spending limit that degrades or blocks requests when hit:
|
||||
|
||||
```bash
|
||||
curl -X POST $OMNIROUTE_URL/api/budget/guard \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"limitUsd": 5.00,
|
||||
"action": "degrade",
|
||||
"degradeTo": "openai/gpt-4o-mini"
|
||||
}'
|
||||
```
|
||||
|
||||
`action` options:
|
||||
|
||||
- `degrade` — switch to a cheaper model when limit is hit
|
||||
- `block` — return 429 when limit is hit
|
||||
- `alert` — continue but add `X-Budget-Warning` header
|
||||
|
||||
## MCP audit log
|
||||
|
||||
OmniRoute logs every MCP tool call to `mcp_audit` table. Query via API:
|
||||
|
||||
```bash
|
||||
curl "$OMNIROUTE_URL/api/mcp/status" \
|
||||
-H "Authorization: Bearer $OMNIROUTE_KEY"
|
||||
```
|
||||
|
||||
Returns: server status, heartbeat, recent audit activity summary.
|
||||
|
||||
## Errors
|
||||
|
||||
- `503` on health endpoint → OmniRoute is starting up; retry in 5s
|
||||
- Circuit breaker `OPEN` → provider is temporarily blocked; check `resetAt` to know when it auto-recovers
|
||||
- `429 budget_exceeded` → budget guard limit reached; raise limit or wait for reset
|
||||
<!-- skill:custom-end -->
|
||||
Reference in New Issue
Block a user