diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-a2a/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-a2a/SKILL.md new file mode 100644 index 0000000000..2783c6261f --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-a2a/SKILL.md @@ -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 diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-chat/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-chat/SKILL.md new file mode 100644 index 0000000000..7f97c73cd0 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-chat/SKILL.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 diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-admin/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-admin/SKILL.md new file mode 100644 index 0000000000..082817cf4d --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-admin/SKILL.md @@ -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 # 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 # 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 # Get a single env var value +omniroute env set # 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 # 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` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-cloud/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-cloud/SKILL.md new file mode 100644 index 0000000000..75e83ef4a6 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-cloud/SKILL.md @@ -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 # Full task record +omniroute cloud codex task status # 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 # Approve the proposed plan +omniroute cloud jules task approve +``` + +## Send a message to a running task + +```bash +omniroute cloud codex task message "Focus on the backend only, skip the UI" +``` + +## List task sources (files touched) + +```bash +omniroute cloud codex task sources # Files changed / created by the task +``` + +## Cancel a task + +```bash +omniroute cloud codex task cancel +omniroute cloud devin task cancel +``` + +## 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 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 diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-eval/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-eval/SKILL.md new file mode 100644 index 0000000000..244097d4b7 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-eval/SKILL.md @@ -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 # 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 \ + --model claude-sonnet-4-6 # Run suite against a specific model + +omniroute eval suites run \ + --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 --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 # Run details (status, model, score) +omniroute eval results # Per-sample results +omniroute eval scorecard # Full scorecard with pass/fail per sample +omniroute eval cancel # Cancel a running eval +``` + +## Scorecard output + +```bash +omniroute eval scorecard --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 ` +- `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 ` until `status` is `completed` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-providers/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-providers/SKILL.md new file mode 100644 index 0000000000..1d8e53a5b9 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli-providers/SKILL.md @@ -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 # 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 [apiKey] # Add an API key for a provider +omniroute keys remove # Remove an API key +omniroute keys regenerate # Regenerate (rotate) a key +omniroute keys revoke # Revoke a key (disables it) +omniroute keys reveal # Show the full key value +omniroute keys usage # Show usage stats for a key + +omniroute keys rotate # Rotate + revoke old key atomically +omniroute keys expiration list # List key expiration times +``` + +### Key policies + +```bash +omniroute keys policy show # Show rate-limit / permission policy +omniroute keys policy set \ + --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 # Start browser-based OAuth flow +omniroute oauth logout # Revoke OAuth token +omniroute oauth status # Show token state + expiry +omniroute oauth refresh # 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 # List nodes for a provider +omniroute nodes add --api-key # Add a node +omniroute nodes remove # Remove a node +omniroute nodes test # Test one node +``` + +## Routing combos (CLI) + +Create and manage routing combos from the terminal: + +```bash +omniroute combo list # List all combos +omniroute combo create \ + --strategy priority \ + --targets anthropic/claude-opus-4-7,openai/gpt-4o # Create combo +omniroute combo switch # Activate a combo as default +omniroute combo delete # 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 ` 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` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli/SKILL.md new file mode 100644 index 0000000000..5229916395 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-cli/SKILL.md @@ -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 ` | Override server URL for this invocation | +| `--api-key ` | Override API key for this invocation | +| `--output ` | 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 ` | 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 diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-compression/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-compression/SKILL.md new file mode 100644 index 0000000000..fd670ead69 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-compression/SKILL.md @@ -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`) diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-embeddings/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-embeddings/SKILL.md new file mode 100644 index 0000000000..f02998092e --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-embeddings/SKILL.md @@ -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` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-image/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-image/SKILL.md new file mode 100644 index 0000000000..9ccd40a170 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-image/SKILL.md @@ -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` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-mcp/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-mcp/SKILL.md new file mode 100644 index 0000000000..594896d1b1 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-mcp/SKILL.md @@ -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 diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-monitoring/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-monitoring/SKILL.md new file mode 100644 index 0000000000..f2f0b23c08 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-monitoring/SKILL.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 diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-routing/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-routing/SKILL.md new file mode 100644 index 0000000000..d0a90de766 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-routing/SKILL.md @@ -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 diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-stt/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-stt/SKILL.md new file mode 100644 index 0000000000..4008b69ffb --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-stt/SKILL.md @@ -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` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-tts/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-tts/SKILL.md new file mode 100644 index 0000000000..f236615ca5 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-tts/SKILL.md @@ -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` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-web-fetch/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-web-fetch/SKILL.md new file mode 100644 index 0000000000..9c009e1954 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-web-fetch/SKILL.md @@ -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` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-web-search/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-web-search/SKILL.md new file mode 100644 index 0000000000..ca169b2305 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute-web-search/SKILL.md @@ -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` diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute/SKILL.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute/SKILL.md new file mode 100644 index 0000000000..6291d47a53 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/omniroute/SKILL.md @@ -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/` +- `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 diff --git a/skills/cli-eval/SKILL.md b/skills/cli-eval/SKILL.md new file mode 100644 index 0000000000..769deff4be --- /dev/null +++ b/skills/cli-eval/SKILL.md @@ -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. +--- + + + + +# 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 # 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 \ + --model claude-sonnet-4-6 # Run suite against a specific model + +omniroute eval suites run \ + --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 --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 # Run details (status, model, score) +omniroute eval results # Per-sample results +omniroute eval scorecard # Full scorecard with pass/fail per sample +omniroute eval cancel # Cancel a running eval +``` + +## Scorecard output + +```bash +omniroute eval scorecard --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 ` +- `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 ` until `status` is `completed` + diff --git a/skills/cli-providers/SKILL.md b/skills/cli-providers/SKILL.md new file mode 100644 index 0000000000..c89747b23e --- /dev/null +++ b/skills/cli-providers/SKILL.md @@ -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. +--- + + + + +# 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 # 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 [apiKey] # Add an API key for a provider +omniroute keys remove # Remove an API key +omniroute keys regenerate # Regenerate (rotate) a key +omniroute keys revoke # Revoke a key (disables it) +omniroute keys reveal # Show the full key value +omniroute keys usage # Show usage stats for a key + +omniroute keys rotate # Rotate + revoke old key atomically +omniroute keys expiration list # List key expiration times +``` + +### Key policies + +```bash +omniroute keys policy show # Show rate-limit / permission policy +omniroute keys policy set \ + --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 # Start browser-based OAuth flow +omniroute oauth logout # Revoke OAuth token +omniroute oauth status # Show token state + expiry +omniroute oauth refresh # 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 # List nodes for a provider +omniroute nodes add --api-key # Add a node +omniroute nodes remove # Remove a node +omniroute nodes test # Test one node +``` + +## Routing combos (CLI) + +Create and manage routing combos from the terminal: + +```bash +omniroute combo list # List all combos +omniroute combo create \ + --strategy priority \ + --targets anthropic/claude-opus-4-7,openai/gpt-4o # Create combo +omniroute combo switch # Activate a combo as default +omniroute combo delete # 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 ` 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` + diff --git a/skills/cli-serve/SKILL.md b/skills/cli-serve/SKILL.md new file mode 100644 index 0000000000..ec638366d0 --- /dev/null +++ b/skills/cli-serve/SKILL.md @@ -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. +--- + + + + +## 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 ` | Override server URL for this invocation | +| `--api-key ` | Override API key for this invocation | +| `--output ` | 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 ` | 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 # 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 # 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 # Get a single env var value +omniroute env set # 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 # 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` + diff --git a/skills/omni-agents-a2a/SKILL.md b/skills/omni-agents-a2a/SKILL.md new file mode 100644 index 0000000000..135edb3022 --- /dev/null +++ b/skills/omni-agents-a2a/SKILL.md @@ -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. +--- + + + + +# 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 + diff --git a/skills/omni-auth/SKILL.md b/skills/omni-auth/SKILL.md new file mode 100644 index 0000000000..03666cd04c --- /dev/null +++ b/skills/omni-auth/SKILL.md @@ -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. +--- + + + + +# 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/` +- `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 + diff --git a/skills/omni-combos-routing/SKILL.md b/skills/omni-combos-routing/SKILL.md new file mode 100644 index 0000000000..a9033a672c --- /dev/null +++ b/skills/omni-combos-routing/SKILL.md @@ -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. +--- + + + + +# 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 + diff --git a/skills/omni-compression/SKILL.md b/skills/omni-compression/SKILL.md new file mode 100644 index 0000000000..ce80c4a920 --- /dev/null +++ b/skills/omni-compression/SKILL.md @@ -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). +--- + + + + +# 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`) + diff --git a/skills/omni-inference/SKILL.md b/skills/omni-inference/SKILL.md new file mode 100644 index 0000000000..2d2d03aaff --- /dev/null +++ b/skills/omni-inference/SKILL.md @@ -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. +--- + + + + +## 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` + diff --git a/skills/omni-mcp/SKILL.md b/skills/omni-mcp/SKILL.md new file mode 100644 index 0000000000..702bc3382d --- /dev/null +++ b/skills/omni-mcp/SKILL.md @@ -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. +--- + + + + +# 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 + diff --git a/skills/omni-resilience/SKILL.md b/skills/omni-resilience/SKILL.md new file mode 100644 index 0000000000..0da3f3830a --- /dev/null +++ b/skills/omni-resilience/SKILL.md @@ -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. +--- + + + + +# 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 +